관심 장소 (POI) 피드

이 페이지에서는 관심 장소 (POI) 피드의 기술 사양을 자세히 설명합니다. 여기에는 필수 필드 요약, 포괄적인 스키마 정의, 구현을 안내하는 JSON 샘플이 포함되어 있습니다.

피드 사양

이 섹션에서는 관심 장소 피드의 요구사항과 정의를 설명합니다.

필드 요구사항

필드 이름 요구사항 설명
poi_id 필수 관심 장소 (숙박 시설)를 식별하는 파트너가 생성한 문자열입니다.
이름 필수 관심 장소의 이름입니다. 이 이름은 애그리게이터 단위에서 속성의 표시 이름으로 사용됩니다.
전화 참고사항 국가 및 지역 번호를 포함한 관심 장소의 연락처 전화번호입니다(예: +14567891234).
URL 참고사항 관심 장소의 공개 웹사이트 URL입니다. 참고: 이 정보는 일치 목적으로만 사용되며 표시되지 않습니다.
위치 필수 (주소)
권장 (위도/경도)		 관심 장소의 위치입니다.
필수: 숙박 시설과 올바르게 일치시키려면 주소 및 관련 입력란이 필요합니다.
선택사항: 위도 및 경도 제공된 경우 Google은 애그리게이터 단위 지도에 숙박 시설 핀을 표시할 때 위도/경도를 사용합니다.
이미지 필수 (이미지 1개)
권장 (여러 개)		 관심 장소의 이미지입니다. 이미지는 숙박 시설을 표시하는 데 중요한 역할을 합니다. 이미지를 1개 이상 추가하는 것이 좋습니다. 이미지는 최대 5개까지 제공할 수 있습니다. 여러 개가 제공되면 제공된 순서대로 사용됩니다 (이미지를 사용할 수 없는 경우).

이미지가 Google의 세이프서치 정책을 위반하지 않는지 확인하기 위해 검토가 진행됩니다.
평가 추천 숙박 시설의 평균 평점입니다.
num_ratings 추천 rating 필드의 평점 수입니다.
rating_scale 참고사항 rating 필드에 사용되는 평가 척도입니다. 최대 평점이 5이면 rating_scale은 5입니다.
카테고리 참고사항 속성의 카테고리를 나타냅니다.
hotel_data 참고사항 호텔 관련 필드입니다. 자세한 내용은 HotelData 정의를 참고하세요.
hotel_star_class 추천 공식 호텔 등급 별표 값입니다. 이 값은 0에서 5 사이의 정수여야 합니다. 시스템에서 별 반 개 또는 소수점 값 (예: 3.5)을 사용하는 경우 정수 (3)로 내림합니다. 별 등급을 사용할 수 없거나, 알 수 없거나, 지정되지 않은 경우 0 값을 제공하세요. 0으로 설정하면 사용자 UI에 호텔 성급이 표시되지 않습니다.
brand_ids 참고사항 이 호텔을 표시할 수 있는 브랜드입니다. 이 필드가 비어 있으면 피드와 연결된 모든 브랜드에 호텔이 표시될 수 있습니다.
설명 참고사항 속성에 대한 자세한 설명입니다.
display_address 참고사항 UI에 표시되는 주소입니다.

이미지 가이드라인

피드에 추가되는 모든 이미지는 다음 가이드라인을 따라야 합니다.

  • 형식: JPEG, PNG 또는 WebP여야 합니다.
  • 최대 파일 크기: 이미지당 30MB 미만
  • 최대 크기: 총 7,500만 픽셀 미만 (너비 x 높이 < 75,000,000)
  • URL 유형: 이미지 확장 소재로 연결되는 직접 경로 (예: .jpg로 끝남)
  • 권한: 호스팅 서버와 robots.txt 파일이 Googlebot 및 Googlebot-Image 사용자 에이전트에 대한 액세스를 허용하고 이미지 디렉터리를 차단하지 않는지 확인합니다.

다국어 지원

관심 장소 피드는 특정 필드에 현지화된 콘텐츠를 제공하는 것을 지원합니다. 다음 필드는 Text 유형이며 현지화를 지원합니다.

  • name
  • description
  • display_address

여러 언어로 콘텐츠를 제공하려면 필드에 default_locale를 지정하고 localizations 목록에 현지화된 문자열을 제공해야 합니다. 단일 관심 장소 항목에 숙박 시설의 모든 현지화를 제공합니다. 여러 언어 JSON 파일 간에 단일 속성을 분할하지 마세요.

예:

"name": {
  "localizations": [
    {
      "locale": "en",
      "text": "Banana Hotel"
    },
    {
      "locale": "es",
      "text": "Hotel Plátano"
    }
  ],
  "default_locale": "en"
}

파일 패키징 가이드라인

성공적인 처리를 위해 다음 패키징 요구사항을 준수하세요.

  • 단일 집계 JSON 보관 파일 (필수): 모든 숙박 시설 레코드를 단일 JSON 파일로 결합합니다. 단일 GZIP 보관 파일로 압축하여 업로드하는 것이 좋습니다.
  • 안티패턴 경고: 동일한 보관 파일에서 숙박 시설당 하나의 파일을 사용하거나 국가별로 구분된 여러 파일을 사용하지 마세요. 이 접근 방식은 지원되지 않으며 추출 실패를 유발합니다.

정의

VssPoiFeed 정의

// Represents a Point of Interest (POI) data feed provided by a partner.
export message VssPoiFeed {
  // The POIs in the feed.
  repeated VssPoi data = 1;
}

VssPoi 정의

// Represents a single Point of Interest (POI) entity e.g. a hotel or
// restaurant.
export message VssPoi {
  // Required. A string generated by the partner that identifies a POI.
  string poi_id = 1;

  // The entity name, telephone, url and location are used to support
  // matching partner inventory with entities already present on Google.

  // Required. The name of the POI.
  Text name = 2;

  // The contact telephone number of the POI including its country and
  // area codes, e.g. +14567891234.
  string telephone = 3 [(datapol.semantic_type) = ST_PHONE_NUMBER];

  // The url of the POI's public website.
  // Note: This will be used just for matching purposes, not for display.
  string url = 4;

  // Required. The location of the POI.
  GeoCoordinates location = 5;

  // The address displayed on the UI.
  Text display_address = 17;

  // Images of the POI.
  // Max number of images: 5.
  repeated Image images = 6;

  // Average rating for the POI.
  float rating = 12;

  // The number of contributing ratings for the `rating` field.
  int64 num_ratings = 13;

  // The rating scale used for the `rating` field. If max rating is 5, then
  // rating_scale is 5.
  int32 rating_scale = 14;

  // Represents the category of the POI.
  // It should match the `additional_data` oneof field below.
  export enum Category {

    UNKNOWN_CATEGORY = 0;
    HOTEL = 1;

    LOCAL = 4;
  }

  // Required. Represents the category of the POI.
  Category category = 9;

  // A description of the POI.
  Text description = 16;

  // Required. Category specific fields.
  // It should match the `category` field above.
  oneof additional_data {
    // Hotel specific fields.
    HotelData hotel_data = 10;


    // Local specific fields.
    LocalData local_data = 15;
  }

}

Text 정의

// Represents a text with localizations.
message Text {
  // Represents a localized string.
  message LocalizedString {
    // The text's language tag, such as "en", "en-US" or "sr-Latn".
    string locale = 1;

    // The text in the specified locale.
    string text = 2;
  }

  // The localized strings.
  repeated LocalizedString localizations = 1;

  // The locale to use as the default language it must be present in the
  // localizations.
  string default_locale = 2;
}

GeoCoordinates 정의

// The Geo data of a location, including latitude, longitude, and address.
message GeoCoordinates {
  option (datapol.msg_semantic_type) = ST_LOCATION;

  // [-90, +90] degrees (inclusive).
  // Required if longitude is set, otherwise nice to have.
  double latitude = 1;

  // [-180, +180] degrees (inclusive).
  // Required if latitude is set, otherwise nice to have.
  double longitude = 2;

  // Required. Address for a location.
  oneof addresses {
    // Postal address of the location.
    PostalAddress address = 3;

  }
}

PostalAddress 정의

// The postal address for the location.
message PostalAddress {
  option (datapol.msg_semantic_type) = ST_LOCATION;

  // Required. The country, using ISO 3166-1 alpha-2 country code, e.g. "US".
  string country = 1;

  // Required. The locality/city, e.g. "Mountain View".
  string locality = 2;

  // The region/state/province, e.g. "CA". This field is only required in
  // countries where region is commonly a part of the address. (optional)
  string region = 3;

  // Required. The postal code, e.g. "94043".
  string postal_code = 4;

  // Required. The street address, e.g. "1600 Amphitheatre Pkwy".
  string street_address = 5;
}

이미지 정의

// Represents an image of the Point of Interest (POI).
export message Image {
  // The url of the image. Google will crawl the media hosted at this URL.
  // Max length: 2000.
  string url = 1;

  // The alternative text to be used for accessibility.
  Text alt_text = 2;
}

HotelData 정의

// Hotel specific feed data.
message HotelData {
  // The official hotel class star value.
  // Can be used in a label like "5-star hotel."
  // This value is expected to be an integer between 0 and 5. A rating of 0
  // should be used if a rating is unavailable or not specified. When
  // set to 0, no star class will be displayed on the UI for users.
  int32 hotel_star_class = 1;

  // Deprecated. Use `brand_landing_pages` instead.
  //
  // The brands that can display this hotel.
  // If this field is empty, the hotel can be displayed under any of the
  // brands associated with the feed.
  repeated string brand_ids = 2
      [(datapol.semantic_type) = ST_PARTNER_ID, deprecated = true];

  // The brand landing pages.
  repeated BrandLandingPages brand_landing_pages = 3;
}

샘플

관심 장소 피드

파일명: poi_1707240000.json

{
  "data": [
    {
      "poi_id": "hotel_banana",
      "name": {
        "localizations": [
          {
            "locale": "en",
            "text": "Banana Hotel"
          }
        ],
        "default_locale": "en"
      },
      "telephone": "+16195550100",
      "url": "https://www.example-banana-hotel.com",
      "location": {
        "latitude": 32.7157,
        "longitude": -117.1611,
        "address": {
          "country": "US",
          "locality": "San Diego",
          "region": "CA",
          "postal_code": "92101",
          "street_address": "2845 W 7th St"
        }
      },
      "images": [
        {
          "url": "https://www.example.com/banana_hotel.jpg",
          "alt_text": {
             "localizations": [
               { "locale": "en", "text": "Banana Hotel Exterior" }
             ]
          }
        }
      ],
      "rating": 4.5,
      "category": "HOTEL",
      "hotel_data": {
        "hotel_star_class": 4,
        "brand_ids": ["brand_a", "brand_b"]
      }
    },
    {
      "poi_id": "hotel_kiwi",
      "name": {
        "localizations": [
          {
            "locale": "en",
            "text": "Kiwi Hotel"
          }
        ],
        "default_locale": "en"
      },
      "telephone": "+41445550100",
      "url": "https://www.example-kiwi-hotel.com",
      "location": {
        "latitude": 47.3769,
        "longitude": 8.5417,
        "address": {
          "country": "CH",
          "locality": "Zurich",
          "postal_code": "8001",
          "street_address": "Bahnhofstrasse 10"
        }
      },
      "images": [
        {
          "url": "https://www.example.com/kiwi_hotel.jpg",
          "alt_text": {
             "localizations": [
               { "locale": "en", "text": "Kiwi Hotel Lobby" }
             ]
          }
        }
      ],
      "rating": 4.0,
      "category": "HOTEL",
      "hotel_data": {
        "hotel_star_class": 3,
        "brand_ids": ["brand_c"]
      }
    },
    {
      "poi_id": "hotel_croissant",
      "name": {
        "localizations": [
          {
            "locale": "en",
            "text": "Croissant Hotel"
          }
        ],
        "default_locale": "en"
      },
      "telephone": "+41445550200",
      "url": "https://www.example-croissant-hotel.com",
      "location": {
        "latitude": 47.3686,
        "longitude": 8.5392,
        "address": {
          "country": "CH",
          "locality": "Zurich",
          "postal_code": "8002",
          "street_address": "Paradeplatz 1"
        }
      },
      "images": [
        {
          "url": "https://www.example.com/croissant_hotel.jpg",
          "alt_text": {
             "localizations": [
               { "locale": "en", "text": "Croissant Hotel View" }
             ]
          }
        }
      ],
      "rating": 5.0,
      "category": "HOTEL",
      "hotel_data": {
        "hotel_star_class": 5
      }
    },
    {
      "poi_id": "hotel_tiburon",
      "name": {
        "localizations": [
          {
            "locale": "en",
            "text": "Hotel Tiburon"
          }
        ],
        "default_locale": "en"
      },
      "telephone": "+15105550100",
      "url": "https://www.example-tiburon-hotel.com",
      "location": {
        "latitude": 37.7652,
        "longitude": -122.2416,
        "address": {
          "country": "US",
          "locality": "Alameda",
          "region": "CA",
          "postal_code": "94501",
          "street_address": "1100 Atlantic Ave"
        }
      },
      "images": [
        {
          "url": "https://www.example.com/tiburon_hotel.jpg",
          "alt_text": {
             "localizations": [
               { "locale": "en", "text": "Hotel Tiburon Pool" }
             ]
          }
        }
      ],
      "rating": 4.2,
      "category": "HOTEL",
      "hotel_data": {
        "hotel_star_class": 5,
        "brand_ids": ["brand_a"]
      }
    }
  ]
}

다국어 관심 장소 피드

파일명: poi_multilingual.json

{
  "data": [
    {
      "poi_id": "hotel_banana_multilingual",
      "name": {
        "localizations": [
          {
            "locale": "en",
            "text": "Banana Hotel"
          },
          {
            "locale": "es",
            "text": "Hotel Plátano"
          },
          {
            "locale": "fr",
            "text": "Hôtel Banane"
          }
        ],
        "default_locale": "en"
      },
      "description": {
        "localizations": [
          {
            "locale": "en",
            "text": "A beautiful hotel shaped like a banana."
          },
          {
            "locale": "es",
            "text": "Un hermoso hotel con forma de plátano."
          },
          {
            "locale": "fr",
            "text": "Un bel hôtel en forme de banane."
          }
        ],
        "default_locale": "en"
      },
      "display_address": {
        "localizations": [
          {
            "locale": "en",
            "text": "123 Banana Way, Fruit City, CA 90000"
          },
          {
            "locale": "es",
            "text": "123 Vía Plátano, Ciudad Fruta, CA 90000"
          }
        ],
        "default_locale": "en"
      },
      "telephone": "+16195550100",
      "url": "https://www.example-banana-hotel.com",
      "location": {
        "latitude": 32.7157,
        "longitude": -117.1611,
        "address": {
          "country": "US",
          "locality": "Fruit City",
          "region": "CA",
          "postal_code": "90000",
          "street_address": "123 Banana Way"
        }
      },
      "images": [
        {
          "url": "https://www.example.com/banana_hotel.jpg",
          "alt_text": {
             "localizations": [
               { "locale": "en", "text": "Banana Hotel Exterior" },
               { "locale": "es", "text": "Exterior del Hotel Plátano" }
             ]
          }
        }
      ],
      "rating": 4.5,
      "category": "HOTEL",
      "hotel_data": {
        "hotel_star_class": 4,
        "brand_ids": ["brand_mango", "brand_apricot"]
      }
    }
  ]
}