Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Plik danych o ciekawych miejscach

Na tej stronie znajdziesz specyfikację techniczną pliku danych o ciekawych miejscach. Zawiera podsumowanie wymaganych pól, kompleksowe definicje schematów i przykładowy plik JSON, który ułatwia implementację.

Specyfikacje pliku danych

W tej sekcji opisujemy wymagania i definicje dotyczące pliku danych o ciekawych miejscach.

Wymagania dotyczące pól

Nazwa pola	Wymaganie	Opis
poi_id	Wymagane	Ciąg znaków wygenerowany przez partnera, który identyfikuje interesujące miejsce (obiekt).
nazwa	Wymagane	Nazwa ciekawego miejsca. Ta nazwa będzie używana jako wyświetlana nazwa obiektu w jednostce agregującej.
telefon	Przydatne	Numer telefonu kontaktowego do ciekawego miejsca, w tym kod kraju i numer kierunkowy, np. +14567891234.
URL	Przydatne	URL publicznej witryny ciekawego miejsca. Uwaga: te informacje będą używane tylko do dopasowywania, a nie do wyświetlania.
lokalizacja	Wymagane (adres) Opcjonalne (szerokość/długość geograficzna)	Lokalizacja ciekawego miejsca. Wymagane: adres i powiązane pola są wymagane, aby prawidłowo dopasować obiekt. Opcjonalne: szerokość i długość geograficzna. Jeśli podasz te informacje, Google użyje szerokości i długości geograficznej do wyświetlania pinezek obiektów na mapie jednostki agregującej.
obrazy	Wymagany (1 obraz) Warto dodać (kilka)	zdjęcia ciekawego miejsca; Obrazy będą ważne podczas wyświetlania właściwości. Zdecydowanie zalecamy dodanie co najmniej 1 obrazu. Możesz przesłać maksymalnie 5 obrazów. Jeśli podasz kilka, zostaną one użyte w kolejności, w jakiej zostały podane (w przypadku, gdy obraz nie będzie nadawał się do użycia). Obrazy zostaną sprawdzone pod kątem zgodności z zasadami Google dotyczącymi bezpiecznego wyszukiwania.
ocena	Zalecane	Średnia ocena obiektu.
num_ratings	Zalecane	Liczba ocen, które wpłynęły na wartość w polu `rating`.
rating_scale	Przydatne	Skala ocen używana w polu `rating`. Jeśli maksymalna ocena to 5, wartość rating_scale wynosi 5.
kategoria	Przydatne	Reprezentuje kategorię usługi.
hotel_data	Przydatne	Pola dotyczące hoteli. Szczegółowe informacje znajdziesz w artykule Definicja HotelData.
hotel_star_class	Zalecane	Oficjalna liczba gwiazdek hotelu. Ta wartość powinna być liczbą całkowitą z zakresu od 0 do 5. Jeśli Twój system używa wartości dziesiętnych lub połówek gwiazdek (np. `3.5`), zaokrąglij je w dół do liczby całkowitej (`3`). Jeśli klasa gwiazdkowa jest niedostępna, nieznana lub nieokreślona, podaj wartość 0. Jeśli ustawisz wartość 0, użytkownikom nie będzie wyświetlana w interfejsie żadna klasa hotelu.
brand_landing_pages	Opcjonalny	Strony docelowe dla konkretnej marki w przypadku obiektu w lokalizacji `hotel_data`. Każdy wpis określa `brand_id` pasujący do marki skonfigurowanej w sekcji Konfiguracja > Marki, `default_url` i opcjonalny `localized_landing_pages`. Więcej informacji znajdziesz w sekcji Definicja BrandLandingPages.
brand_ids	Wycofano	Wycofana. Zamiast niej używaj zasady `brand_landing_pages`. Marki, które mogą wyświetlać ten hotel. Jeśli to pole jest puste, hotel może się wyświetlać pod dowolną marką powiązaną z plikiem danych.
opis	Przydatne	Szczegółowy opis obiektu.
display_address	Przydatne	Adres wyświetlany w interfejsie.

Wytyczne dotyczące obrazów

Wszystkie obrazy dodane do pliku danych muszą być zgodne z tymi wytycznymi:

Format: JPEG, PNG lub WebP.
Maksymalny rozmiar pliku: poniżej 30 MB na obraz.
Maksymalne wymiary: mniej niż 75 megapikseli (szerokość × wysokość < 75 000 000).
Typ adresu URL: bezpośrednia ścieżka do komponentu z obrazem (np. kończąca się rozszerzeniem .jpg).
Uprawnienia: upewnij się, że serwer hostujący i plik robots.txt zezwalają na dostęp klientom użytkownika Googlebot i Googlebot-Image oraz nie blokują katalogów z obrazami.

Obsługa wielu języków

Plik danych o ciekawych miejscach obsługuje podawanie zlokalizowanych treści w określonych polach. Te pola są typu Text i obsługują lokalizację:

name
description
display_address

Aby udostępniać treści w kilku językach, musisz określić default_locale w polu i podać zlokalizowane ciągi znaków na liście localizations. Podaj wszystkie lokalizacje usługi w jednym wpisie dotyczącym ważnego miejsca. Nie dziel jednej właściwości między pliki JSON w różnych językach.

Przykład:

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

Wytyczne dotyczące pakowania plików

Aby zapewnić prawidłowe przetwarzanie, przestrzegaj tych wymagań dotyczących pakowania:

Pojedyncze zagregowane archiwum JSON (wymagane): połącz wszystkie rekordy obiektów w jeden plik JSON. Zalecamy skompresowanie go do jednego archiwum GZIP i przesłanie.
Ostrzeżenie dotyczące antywzorca: nie używaj jednego pliku na obiekt ani wielu plików rozdzielonych według kraju w tym samym archiwum. Takie podejście nie jest obsługiwane i będzie powodować błędy wyodrębniania.

Definicje

Definicja pliku danych 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 {

    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;
  }

}

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 współrzędnych geograficznych

// 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 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;
}

Definicja BrandLandingPages

// The Localized brand landing pages for a single Point of Interest (POI).
message BrandLandingPages {
  // Required. 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".
    // Empty list means this page is not restricted by language.
    repeated string locales = 3;

    // Restricts this page to users from the specified countries.
    // Must contain ISO 3166-1 alpha-2 country codes, e.g. "US".
    // Empty list means this page is not restricted by country.
    // If `is_default_for_country` is true, this field must not be empty.
    repeated string countries = 4;

    // Whether this page should be used as the default fallback for users in
    // `countries` when no entry for that country matches the user's
    // language preference.
    bool is_default_for_country = 5;
  }

  // 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;

  // Required. 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