本頁詳細說明搜尋點 (POI) 動態饋給的技術規格。其中包含必填欄位的摘要、完整的結構定義，以及可做為實作指南的 JSON 範例。
動態饋給規格
本節說明 POI 動態饋給的規定和定義。
欄位規定
| 欄位名稱 | 規定 | 說明 |
|---|---|---|
| poi_id | 必填 | 合作夥伴產生的字串，用於識別搜尋點 (房源)。 |
| 名稱 | 必填 | 地標名稱。這個名稱會做為匯總器單元中的資源顯示名稱。 |
| 電話 | 建議條件 | POI 的聯絡電話號碼 (包含所在國家/地區代碼)，例如 +14567891234。 |
url |
建議條件 | 地標的公開網站網址。附註：這項資訊僅用於比對，不會顯示。 |
| 位置 | 必要 (地址) 建議提供 (經緯度) |
搜尋點的位置。 必要：系統會要求提供位址和相關欄位，以便正確比對房源。 建議：提供緯度和經度。如果提供經緯度，Google 會在匯總單元地圖中顯示房源圖釘時使用這些資訊。 |
| 圖片 | 極力建議 (一張圖片) 建議提供 (多張圖片) |
搜尋點的圖片。圖片在顯示房源時非常重要。強烈建議至少加入 1 張圖片。你最多可以提供 5 張圖片。如果提供多張圖片，系統會依提供順序使用 (如果圖片無法使用)。 系統會審查圖片，確保圖片未違反 Google 的安全搜尋政策。 |
| rating | 建議條件 | 房源的平均評分。 |
| num_ratings | 建議條件 | rating 欄位的評分次數。 |
| rating_scale | 建議條件 | 「rating」欄位使用的分級量表。如果最高評分為 5，則 rating_scale 為 5。 |
| category | 建議條件 | 代表資源的類別。 |
| hotel_data | 建議條件 | 飯店專屬欄位。詳情請參閱「HotelData 定義」。 |
| hotel_star_class | 建議條件 | 飯店的官方星級評等值。這個值應為介於 1 到 5 之間的整數。 |
| brand_ids | 建議條件 | 可顯示這間飯店的品牌。如果這個欄位空白，飯店可能會顯示在與動態饋給相關聯的任何品牌下。 |
| 說明 | 建議條件 | 資源的詳細說明。 |
| display_address | 建議條件 | 使用者介面上顯示的地址。 |
圖片使用規範
加入動態消息的所有圖片都必須符合下列規範：
- 格式：必須為 JPEG、PNG 或 WebP。
- 檔案大小上限：每張圖片不得超過 30 MB。
- 最大尺寸：總像素數不得超過 7,500 萬 (寬 x 高 < 75,000,000)。
- 網址類型：圖片素材資源的直接路徑 (例如結尾為 .jpg)。
- 權限：確認代管伺服器允許 Googlebot 或檢索器存取，且沒有 robots.txt 封鎖圖片目錄。
支援多種語言
搜尋點動態饋給支援為特定欄位提供在地化內容。下列欄位屬於 Text 類型，並支援本地化：
namedescriptiondisplay_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 1 and 5. int32 hotel_star_class = 1; // 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]; }
範例
搜尋點動態消息
檔案名稱：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"] } } ] }