Tworzenie i przesyłanie plików danych o punktach POI
Podczas tworzenia i przesyłania plików danych o punktach POI postępuj zgodnie z tymi instrukcjami:
- W przypadku plików danych o punktach POI postępuj zgodnie ze specyfikacją opisaną w pliku danych o punktach POI. Zalecamy używanie unikalnych nazw plików danych o punktach POI w przypadku każdego przesłania. W nazwie pliku umieść sygnaturę czasową, np.
POI_1633621547.json. - Przesyłaj pliki danych na serwer SFTP lokalnych punktów POI codziennie w ramach pełnego odświeżania.
- Szczegóły serwera SFTP znajdziesz w sekcji Konfiguracja > Pliki danych w Portalu dla partnerów.
- Stan przetwarzania pliku danych możesz sprawdzić w sekcji Przetwarzanie > Historia w portalu dla partnerów.
Specyfikacje pliku danych
Wymagania dotyczące pól
VssPoi
Reprezentuje pojedynczy obiekt typu ważne miejsce (POI), np. hotel lub restaurację.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
poi_id | tekst | Wymagane | Wymagane. Ciąg znaków wygenerowany przez partnera, który identyfikuje punkt POI. |
name | object(Text) | Wymagane | Wymagane. Nazwa punktu. |
telephone | tekst | Numer telefonu punktu, w tym kod kraju i numer kierunkowy, np. +14567891234. | |
url | tekst | Adres URL publicznej witryny internetowej punktu. Uwaga: będzie to używane tylko do dopasowywania, a nie do wyświetlania. | |
location | object(GeoCoordinates) | Wymagane | Wymagane. Lokalizacja punktu POI. |
display_address | object(Text) | Adres wyświetlany w interfejsie. | |
images | tablica obiektów(Image) | zdjęcia ważnego miejsca; Maksymalna liczba obrazów: 5. | |
rating | liczba | Średnia ocena punktu. | |
num_ratings | liczba | Liczba ocen, które przyczyniły się do wartości pola rating. | |
rating_scale | liczba | Skala oceniania używana w przypadku pola rating. Jeśli maksymalna ocena to 5, to skala_ocen to 5. | |
category | enum(Category) | Wymagane | Wymagane. Reprezentuje kategorię punktu POI. |
description | object(Text) | Opis punktu POI. | |
| oneOf(additional_data) | Wymagane | Można ustawić tylko jedno z pól w tym polu oneOf. |
Tekst
Reprezentuje tekst z lokalizacjami.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
localizations | tablica obiektów(LocalizedString) | Zlokalizowane ciągi znaków. | |
default_locale | tekst | Region, który ma być używany jako język domyślny, musi być obecny w lokalizacjach. |
LocalizedString
Reprezentuje zlokalizowany ciąg znaków.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
locale | tekst | Tag języka tekstu, np. „en”, „en-US” lub „sr-Latn”. | |
text | tekst | Tekst w określonym języku. |
GeoCoordinates
Dane geograficzne lokalizacji, w tym szerokość i długość geograficzna oraz adres.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
latitude | liczba | [-90, +90] stopni (włącznie). Wymagane, jeśli ustawiona jest długość geograficzna. W przeciwnym razie jest to opcjonalne. | |
longitude | liczba | [-180, +180] stopni (włącznie). Wymagane, jeśli ustawiona jest szerokość geograficzna. W przeciwnym razie jest to opcjonalne. | |
| oneOf(addresses) | Wymagane | Można ustawić tylko jedno z pól w tym polu oneOf. |
PostalAddress
Adres pocztowy lokalizacji.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
country | tekst | Wymagane | Wymagane. Kraj podany w postaci kodu ISO 3166-1 alfa-2, np. „US”. |
locality | tekst | Wymagane | Wymagane. Miejscowość, np. „Mountain View”. |
region | tekst | Region/stan/prowincja, np. „CA”. To pole jest wymagane tylko w krajach, w których region jest zwykle częścią adresu. (opcjonalnie) | |
postal_code | tekst | Wymagane | Wymagane. Kod pocztowy, np. „94043”. |
street_address | tekst | Wymagane | Wymagane. Ulica, np. „1600 Amphitheatre Pkwy”. |
Obraz
Reprezentuje obraz ciekawego miejsca.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
url | tekst | Adres URL obrazu. Google zindeksuje multimedia hostowane pod tym adresem URL. Maksymalna długość: 2000. | |
alt_text | object(Text) | Tekst alternatywny, który ma być używany na potrzeby ułatwień dostępu. |
HotelData
Dane z pliku danych o hotelach.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
hotel_star_class | liczba | Oficjalna klasa hotelu wyrażona w gwiazdkach. Może być używany w etykiecie, np. „hotel 5-gwiazdkowy”. Ta wartość powinna być liczbą całkowitą z zakresu od 1 do 5. | |
brand_ids | tablica ciągów znaków | Marki, które mogą wyświetlać ten hotel. Jeśli to pole jest puste, hotel może być wyświetlany w ramach dowolnej marki powiązanej z plikiem danych. |
LocalData
dane z pliku dotyczące konkretnego obiektu,
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
business_hours | object(BusinessHours) | Standardowe godziny otwarcia placówki. | |
price_range | object(PriceRange) | Przedział cenowy usług oferowanych przez obiekt. | |
establishment_category | object(Text) | Rodzaj placówki. | |
brand_landing_pages | tablica obiektów(BrandLandingPages) | Strony docelowe marki. |
BusinessHours
Określa przedziały czasowe, w których ta lokalizacja jest otwarta. Zawiera kolekcję instancji [TimeRange][madden.vss_poi_feed.TimeRange]. Przykład: otwarte w soboty od 9:00 do 12:00 i od 13:00 do 17:00: time_ranges { open_day: SATURDAY open_time: { hours: 9, minutes: 0 } close_day: SATURDAY close_time: { hours: 12, minutes: 0 } } time_rages { open_day: SATURDAY open_time: { hours: 13, minutes: 0 } close_day: SATURDAY close_time: { hours: 17, minutes: 0 } } Przykład: otwarte w soboty od 21:00 do niedzieli do 2:00: time_ranges { open_day: SATURDAY open_time: { hours: 21, minutes: 0 } close_day: SUNDAY close_time: { hours: 2, minutes: 0 } }
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
time_ranges | tablica obiektów(TimeRange) | Zbiór godzin, w których ten punkt jest otwarty. Każdy okres to zakres godzin, w których punkt jest otwarty w ciągu tygodnia. |
TimeRange
Reprezentuje okres, w którym punkt usługowy jest otwarty, począwszy od określonego dnia i godziny otwarcia, a kończąc na określonym dniu i godzinie zamknięcia. Godzina zamknięcia musi przypadać po godzinie otwarcia, np. później tego samego dnia lub w kolejnym dniu.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
open_day | enum(DayOfWeek) | Dzień otwarcia w zakresie czasu. | |
open_time | object(TimeOfDay) | Godzina otwarcia w zakresie czasu. | |
close_day | enum(DayOfWeek) | Dzień zamknięcia przedziału czasowego. | |
close_time | object(TimeOfDay) | Godzina zamknięcia zakresu czasu. |
TimeOfDay
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
hours | liczba | Godziny w formacie 24-godzinnym. Wartość musi być równa lub większa niż 0 i zwykle nie może być większa niż 23. Interfejs API może zezwalać na wartość „24:00:00” w przypadku takich scenariuszy jak godzina zamknięcia firmy. | |
minutes | liczba | Minuty w godzinie. Wartość musi być równa lub większa niż 0 i równa lub mniejsza niż 59. | |
seconds | liczba | Sekundy w minucie. Wartość musi być równa lub większa niż 0 i zwykle nie może być większa niż 59. Interfejs API może zezwalać na wartość 60, jeśli dopuszcza sekundy przestępne. | |
nanos | liczba | Ułamki sekund w nanosekundach. Wartość musi być równa lub większa niż 0 i mniejsza lub równa 999 999 999. |
PriceRange
Przedział cenowy usług oferowanych przez punkt.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
min_price | object(Money) | Cena minimalna usług oferowanych przez punkt. | |
max_price | object(Money) | Cena maksymalna usług oferowanych przez punkt. |
Pieniądze
Reprezentuje kwotę pieniędzy z określeniem rodzaju waluty.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
currency_code | tekst | Trzyliterowy kod waluty zdefiniowany w normie ISO 4217. | |
units | liczba | Całe jednostki kwoty.
Jeśli na przykład currencyCode to "USD", to 1 jednostka to 1 PLN. | |
nanos | liczba | Liczba jednostek nano (10^-9) kwoty.
Wartość musi się mieścić w przedziale od -999 999 999 do +999 999 999 (włącznie).
Jeśli wartość units jest dodatnia, wartość nanos musi być dodatnia lub wynosić zero.
Jeśli units wynosi zero, nanos może być dodatnia, ujemna lub równa zero.
Jeśli wartość units jest ujemna, wartość nanos musi być ujemna lub wynosić zero.
Na przykład wartość $-1,75 jest przedstawiana jako units=-1 i nanos=-750 000 000. |
BrandLandingPages
Zlokalizowane strony docelowe marki dla jednego ciekawego miejsca.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
brand_id | tekst | Marka, której dotyczy ta konfiguracja. | |
localized_landing_pages | tablica obiektów(LocalizedLandingPage) | przetłumaczone strony docelowe; Wartości pól url i locales muszą być unikalne we wszystkich zlokalizowanych stronach docelowych. | |
default_url | tekst | Domyślny adres URL strony docelowej, który ma być używany, gdy żadna ze zlokalizowanych stron docelowych nie pasuje do języka użytkownika. |
LocalizedLandingPage
zlokalizowana strona docelowa dla ciekawego miejsca,
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
url | tekst | Adres URL strony docelowej. Maksymalna długość: 2000. | |
locales | tablica ciągów znaków | Ogranicza dostęp do tej strony do użytkowników z określonym ustawieniem języka. Musi zawierać tagi języka, np. „en”, „en-US” lub „sr-Latn”. |
Kategoria
Reprezentuje kategorię punktu POI.
Powinno pasować do pola additional_data oneof poniżej.
| Nazwa | Opis |
|---|---|
UNKNOWN_CATEGORY | |
HOTEL | |
LOCAL |
DzieńTygodnia
Reprezentuje dzień tygodnia.
| Nazwa | Opis |
|---|---|
DAY_OF_WEEK_UNSPECIFIED | Dzień tygodnia jest nieokreślony. |
MONDAY | Poniedziałek |
TUESDAY | Tuesday (wtorek) |
WEDNESDAY | Wednesday (środa) |
THURSDAY | Thursday (czwartek) |
FRIDAY | Friday (piątek) |
SATURDAY | Saturday (sobota) |
SUNDAY | Niedziela |
additional_data
Wymagane. Pola dotyczące określonej kategorii.
Powinno ono być zgodne z polem category powyżej.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
hotel_data | object(HotelData) | Wzajemnie wykluczające się z | Pola dotyczące konkretnego hotelu. |
local_data | object(LocalData) | Wzajemnie wykluczające się z | Pola dotyczące konkretnych lokalizacji. |
adresy
Wymagane. Adres lokalizacji.
| Nazwa pola | Typ | Wymaganie | Opis |
|---|---|---|---|
address | object(PostalAddress) | Adres pocztowy lokalizacji. |
- Format: musi to być plik w formacie JPEG, PNG lub WebP.
- Maksymalny rozmiar pliku: poniżej 30 MB na obraz.
- Maksymalne wymiary: łącznie mniej niż 75 megapikseli (szerokość x wysokość < 75 000 000).
- Typ adresu URL: bezpośrednia ścieżka do komponentu z obrazem (np. kończy się ciągiem .jpg).
- Uprawnienia: upewnij się, że serwer hosta zezwala na dostęp robotom Googlebot lub robotom indeksującym i nie ma pliku robots.txt blokującego katalogi obrazów.
Definicje
Definicja 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; }
Definicja 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 { 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 { // Local specific fields. LocalData local_data = 15; } }
Definicja tekstu
// 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; }
Definicja 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; } }
Definicja 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; }
Definicja obrazu
// 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; }
Definicja LocalData
// Establishment specific feed data. message LocalData { // The regular business hours of the establishment. BusinessHours business_hours = 1; // Price range of the services offered by the establishment. PriceRange price_range = 2; // The type of establishment. Text establishment_category = 3; // The brand landing pages. repeated BrandLandingPages brand_landing_pages = 4; }
Definicja BrandLandingPages
// The Localized brand landing pages for a single Point of Interest (POI). message BrandLandingPages { // The brand this configuration applies to. string brand_id = 1 [(datapol.semantic_type) = ST_PARTNER_ID]; // Localized landing page for the Point of Interest (POI). message LocalizedLandingPage { // The url of the landing page. // Max length: 2000. string url = 1; // Restricts this page to users with the specified language preference. // Must contain language tags, such as "en", "en-US" or "sr-Latn". repeated string locales = 3; } // The localized landing pages. // The url and locales fields values must be unique across all the localized // landing pages. repeated LocalizedLandingPage localized_landing_pages = 2; // The default landing page url to be used when none of the localized // landing pages matches the user's language. string default_url = 3; }
Przykłady
Źródło danych o ciekawych miejscach
Nazwa pliku: poi_1707240000.json
{ "data": [ { "poi_id": "test_restaurant_1", "name": { "localizations": [ { "locale": "en", "text": "Tasty Bites Test Restaurant" } ], "default_locale": "en" }, "telephone": "+1234567890", "url": "https://www.tastybitestest.com", "location": { "latitude": 37.422, "longitude": -122.084, "address": { "country": "US", "locality": "Mountain View", "postal_code": "94043", "street_address": "1600 Amphitheatre Pkwy" } }, "display_address": { "localizations": [ { "locale": "en", "text": "1600 Amphitheatre Pkwy, Mountain View, CA 94043" } ], "default_locale": "en" }, "images": [ { "url": "https://www.tastybitestest.com/images/interior.jpg", "alt_text": { "localizations": [ { "locale": "en", "text": "Cozy dining area of Tasty Bites" } ], "default_locale": "en" } } ], "rating": 4.7, "num_ratings": 150, "rating_scale": 5, "category": "LOCAL", "description": { "localizations": [ { "locale": "en", "text": "A mock restaurant for testing the POI feed ingestion." } ], "default_locale": "en" }, "local_data": { "establishment_category": { "localizations": [ { "locale": "en", "text": "Restaurant" } ], "default_locale": "en" }, "price_range": { "min_price": { "currency_code": "USD", "units": 15, "nanos": 0 }, "max_price": { "currency_code": "USD", "units": 45, "nanos": 0 } }, "business_hours": { "time_ranges": [ { "open_day": "MONDAY", "open_time": { "hours": 11, "minutes": 0 }, "close_day": "MONDAY", "close_time": { "hours": 21, "minutes": 0 } }, { "open_day": "TUESDAY", "open_time": { "hours": 11, "minutes": 0 }, "close_day": "TUESDAY", "close_time": { "hours": 21, "minutes": 0 } }, { "open_day": "WEDNESDAY", "open_time": { "hours": 11, "minutes": 0 }, "close_day": "WEDNESDAY", "close_time": { "hours": 21, "minutes": 0 } }, { "open_day": "THURSDAY", "open_time": { "hours": 11, "minutes": 0 }, "close_day": "THURSDAY", "close_time": { "hours": 22, "minutes": 0 } }, { "open_day": "FRIDAY", "open_time": { "hours": 11, "minutes": 0 }, "close_day": "FRIDAY", "close_time": { "hours": 23, "minutes": 0 } }, { "open_day": "SATURDAY", "open_time": { "hours": 10, "minutes": 0 }, "close_day": "SATURDAY", "close_time": { "hours": 23, "minutes": 0 } }, { "open_day": "SUNDAY", "open_time": { "hours": 10, "minutes": 0 }, "close_day": "SUNDAY", "close_time": { "hours": 20, "minutes": 0 } } ] }, "brand_landing_pages": [ { "brand_id": "tasty_bites_brand", "localized_landing_pages": [ { "url": "https://www.tastybitestest.com/en", "locales": ["en-US", "en-GB"] } ], "default_url": "https://www.tastybitestest.com" }, { "brand_id": "delicious_eats_brand", "localized_landing_pages": [ { "url": "https://www.deliciouseats.com/en", "locales": ["en-US", "en-GB"] } ], "default_url": "https://www.deliciouseats.com" } ] } } ] }
Plik danych z informacjami o wielojęzycznych ważnych miejscach
Nazwa pliku: poi_multilingual.json
{ "data": [ { "poi_id": "test_restaurant_1", "name": { "localizations": [ { "locale": "en", "text": "Tasty Bites Test Restaurant" }, { "locale": "fr", "text": "Restaurant de test Tasty Bites" } ], "default_locale": "en" }, "telephone": "+1234567890", "url": "https://www.tastybitestest.com", "location": { "latitude": 37.422, "longitude": -122.084, "address": { "country": "US", "locality": "Mountain View", "postal_code": "94043", "street_address": "1600 Amphitheatre Pkwy" } }, "display_address": { "localizations": [ { "locale": "en", "text": "1600 Amphitheatre Pkwy, Mountain View, CA 94043" }, { "locale": "fr", "text": "1600 Amphitheatre Pkwy, Mountain View, CA 94043" } ], "default_locale": "en" }, "images": [ { "url": "https://www.tastybitestest.com/images/interior.jpg", "alt_text": { "localizations": [ { "locale": "en", "text": "Cozy dining area of Tasty Bites" }, { "locale": "fr", "text": "Espace salle à manger accueillant de Tasty Bites" } ], "default_locale": "en" } } ], "rating": 4.7, "num_ratings": 150, "rating_scale": 5, "category": "LOCAL", "description": { "localizations": [ { "locale": "en", "text": "A mock restaurant for testing the POI feed ingestion." }, { "locale": "fr", "text": "Un faux restaurant pour tester l'ingestion de flux de points d'intérêt." } ], "default_locale": "en" }, "local_data": { "establishment_category": { "localizations": [ { "locale": "en", "text": "Restaurant" }, { "locale": "fr", "text": "Restaurant" } ], "default_locale": "en" }, "price_range": { "min_price": { "currency_code": "USD", "units": 15, "nanos": 0 }, "max_price": { "currency_code": "USD", "units": 45, "nanos": 0 } }, "business_hours": { "time_ranges": [ { "open_day": "MONDAY", "open_time": { "hours": 11, "minutes": 0 }, "close_day": "MONDAY", "close_time": { "hours": 21, "minutes": 0 } }, { "open_day": "TUESDAY", "open_time": { "hours": 11, "minutes": 0 }, "close_day": "TUESDAY", "close_time": { "hours": 21, "minutes": 0 } }, { "open_day": "WEDNESDAY", "open_time": { "hours": 11, "minutes": 0 }, "close_day": "WEDNESDAY", "close_time": { "hours": 21, "minutes": 0 } }, { "open_day": "THURSDAY", "open_time": { "hours": 11, "minutes": 0 }, "close_day": "THURSDAY", "close_time": { "hours": 22, "minutes": 0 } }, { "open_day": "FRIDAY", "open_time": { "hours": 11, "minutes": 0 }, "close_day": "FRIDAY", "close_time": { "hours": 23, "minutes": 0 } }, { "open_day": "SATURDAY", "open_time": { "hours": 10, "minutes": 0 }, "close_day": "SATURDAY", "close_time": { "hours": 23, "minutes": 0 } }, { "open_day": "SUNDAY", "open_time": { "hours": 10, "minutes": 0 }, "close_day": "SUNDAY", "close_time": { "hours": 20, "minutes": 0 } } ] }, "brand_landing_pages": [ { "brand_id": "tasty_bites_brand", "localized_landing_pages": [ { "url": "https://www.tastybitestest.com/fr", "locales": ["fr-FR", "fr-CA"] }, { "url": "https://www.tastybitestest.com/en", "locales": ["en-US", "en-GB"] } ], "default_url": "https://www.tastybitestest.com" }, { "brand_id": "delicious_eats_brand", "localized_landing_pages": [ { "url": "https://www.deliciouseats.com/fr", "locales": ["fr-FR", "fr-CA"] }, { "url": "https://www.deliciouseats.com/en", "locales": ["en-US", "en-GB"] } ], "default_url": "https://www.deliciouseats.com" } ] } } ] }