This page details the technical specifications for the Point of Interest (POI) feed. It includes a summary of required fields, comprehensive schema definitions, and a JSON sample to guide implementation.
Feed Specifications
This section describes the requirements and definitions for the POI feed.
Field Requirements
| Field Name | Requirement | Description |
|---|---|---|
| poi_id | Required | A string generated by the partner that identifies a point of interest (property). |
| name | Required | The name of the POI. This name will be used as the display name of the property in the Aggregator Unit. |
| telephone | Nice to have | The contact telephone number of the POI including its country and area codes, for example +14567891234. |
| url | Nice to have | The URL of the POI's public website. Note: This will be used just for matching purposes, not for display. |
| location | Required (Address) Nice to have (Lat/Long) |
The location of the POI. Required: The address and accompanying fields will be required to properly match the property. Nice to have: The latitude and longitude. If provided, Google will use the lat/long in the display of property pins in your Aggregator Unit map. |
| images | Required (One image) Nice to have (Multiple) |
Images of the POI. Images will be important in the display of properties. We highly recommend adding a minimum of 1 image. You may provide multiple images up to a max number of 5. When multiple are provided, they will be used in the order that they were provided (in the case of an image being unusable). Images will be reviewed to ensure they don't violate Google's safe search policies. |
| rating | Recommended | Average rating for the property. |
| num_ratings | Recommended | The number of contributing ratings for the rating field. |
| rating_scale | Nice to have | The rating scale used for the rating field. If max rating is 5, then rating_scale is 5. |
| category | Nice to have | Represents the category of the property. |
| hotel_data | Nice to have | Hotel specific fields. See HotelData Definition for details. |
| hotel_star_class | Recommended | The official hotel class star value. This value is expected to be an integer between 0 and 5. Please provide a value of 0 if the star class rating is unavailable, unknown, or not specified. When set to 0, no hotel star class will be displayed on the UI for users. |
| brand_ids | Nice to have | 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. |
| description | Nice to have | A detailed description of the property. |
| display_address | Nice to have | The address displayed on the UI. |
Image Guidelines
All images added to the feed must follow these guidelines:
- Format: Must be JPEG, PNG, or WebP.
- Max File Size: Under 30 MB per image.
- Max Dimensions: Less than 75 Megapixels total (width x height < 75,000,000).
- URL Type: Direct path to the image asset (e.g., ends in .jpg).
- Permissions: Ensure the hosting server allows access to Googlebot or Crawlers and has no robots.txt blocking the image directories.
Multi-lingual Support
The Point of Interest feed supports providing localized content for specific
fields. The following fields are of type Text and support localization:
namedescriptiondisplay_address
To provide content in multiple languages, you must specify a default_locale in
the field and provide the localized strings in the localizations list.
Provide all localizations for a property in a single POI entry. Don't split a
single property among multiple language JSON files.
Example:
"name": {
"localizations": [
{
"locale": "en",
"text": "Banana Hotel"
},
{
"locale": "es",
"text": "Hotel Plátano"
}
],
"default_locale": "en"
}
File Packaging Guidelines
To ensure successful ingestion, adhere to the following packaging requirements:
- Single Aggregated JSON Archive (Required): Combine all property records into one single JSON file. We recommend compressing it into a single GZIP archive, and uploading it.
- Anti-Pattern Warning: Do not use one file per property or multiple files separated by country in the same archive. This approach is not supported and will cause extraction failures.
Definitions
VssPoiFeed Definition
// 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 Definition
// 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 Definition
// 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 Definition
// 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 Definition
// 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; }
Image Definition
// 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 Definition
// 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; // 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]; }
Samples
Point of Interest Feed
Filename: 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"] } } ] }
Multi-lingual POI Feed
Filename: 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"] } } ] }