本页详细介绍了地图注点 (POI) Feed 的技术规范。其中包含必需字段的摘要、全面的架构定义以及用于指导实现的 JSON 示例。
Feed 规范
本部分介绍了 POI Feed 的要求和定义。
字段要求
| 字段名称 | 要求 | 说明 |
|---|---|---|
| poi_id | 必填 | 合作伙伴生成的用于标识地图注点（房源）的字符串。 |
| name | 必填 | 相应 POI 的名称。此名称将用作媒体资源在聚合器单元中的显示名称。 |
| 电话 | 建议条件 | POI 的联系电话号码，包括国家/地区代码和区号，例如 +14567891234。 |
url |
建议条件 | 相应 POI 的公共网站的网址。注意：此信息仅用于匹配目的，不会显示。 |
| 地理位置 | 必需（地址） 最好有（纬度/经度） |
POI 的位置。 必需：需要提供地址和随附字段，以便正确匹配房源。 最好提供：纬度和经度。如果提供，Google 将在您的聚合器单元地图中显示房源图钉时使用相应纬度/经度。 |
| 图片 | 强烈推荐（一张图片） 最好有（多张图片） |
POI 的图片。图片在房源展示中将发挥重要作用。我们强烈建议您至少添加 1 张图片。您最多可以提供 5 张图片。如果提供了多个，系统将按提供的顺序使用它们（如果某个图片无法使用）。 图片将接受审核，以确保其不违反 Google 的安全搜索政策。 |
| 评分 | 建议条件 | 相应房源的平均评分。 |
| num_ratings | 建议条件 | rating 字段的贡献评分数量。 |
| rating_scale | 建议条件 | 用于 rating 字段的评分量表。如果最高评分为 5，则 rating_scale 为 5。 |
| 类别 | 建议条件 | 表示媒体资源的类别。 |
| hotel_data | 建议条件 | 酒店专用字段。如需了解详情，请参阅 HotelData 定义。 |
| hotel_star_class | 建议条件 | 酒店的官方星级值。此值应为介于 1 到 5 之间的整数。 |
| brand_ids | 建议条件 | 可展示此酒店的品牌。如果此字段为空，则酒店可以显示在与相应 Feed 相关联的任何品牌下。 |
| 说明 | 建议条件 | 房源的详细说明。 |
| display_address | 建议条件 | 界面上显示的地址。 |
多语言支持
地图注点 Feed 支持为特定字段提供本地化内容。以下字段属于 Text 类型，支持本地化：
namedescriptiondisplay_address
如需提供多种语言的内容，您必须在字段中指定 default_locale，并在 localizations 列表中提供本地化字符串。在单个 POI 条目中提供房源的所有本地化版本。请勿将单个属性拆分到多个语言 JSON 文件中。
示例：
"name": {
"localizations": [
{
"locale": "en",
"text": "Banana Hotel"
},
{
"locale": "es",
"text": "Hotel Plátano"
}
],
"default_locale": "en"
}
文件打包指南
为确保成功提取，请遵循以下打包要求：
- 单个汇总 JSON 归档文件（必需）：将所有房源记录合并为一个 JSON 文件。我们建议将此单个文件压缩为单个 GZIP 或 ZIP 归档文件（首选 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]; }
示例
地图注点 Feed
文件名：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 Feed
文件名：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"] } } ] }