Plik danych o ciekawych miejscach

Na tej stronie znajdziesz szczegółowe informacje o specyfikacjach technicznych pliku danych o ciekawych miejscach. Zawiera on podsumowanie wymaganych pól, obszerne definicje schematu i przykładowy plik JSON, który ułatwia wdrożenie.

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 punkt zainteresowania (obiekt).
nazwa Wymagane Nazwa punktu. Ta nazwa będzie używana jako wyświetlana nazwa usługi w jednostce agregującej.
telefon Przydatne Numer telefonu punktu, w tym kod kraju i numer kierunkowy, np. +14567891234.
URL Przydatne URL publicznej witryny punktu. Uwaga: będzie to używane tylko do dopasowywania, a nie do wyświetlania.
lokalizacja Wymagany (adres)
Przydatny (szerokość i długość geograficzna)		 Lokalizacja POI.
Wymagane: adres i powiązane z nim pola są wymagane, aby prawidłowo dopasować obiekt.
Przydatne: szerokość i długość geograficzna. Jeśli podasz te dane, Google użyje ich do wyświetlania pinezek obiektów na mapie jednostki agregatora.
obrazy Wymagane (1 obraz)
Przydatne (wiele)		 zdjęcia ważnego miejsca; Obrazy będą ważne w wyświetlaniu informacji o obiektach. Zdecydowanie zalecamy dodanie co najmniej 1 zdjęcia. Możesz przesłać maksymalnie 5 obrazów. Jeśli podasz kilka obrazów, będą one używane w kolejności, w jakiej zostały przesłane (w przypadku, gdy obraz nie będzie się nadawał do użycia).

Obrazy zostaną sprawdzone pod kątem zgodności z zasadami bezpiecznego wyszukiwania Google.
ocena Zalecane Średnia ocena usługi.
num_ratings Zalecane Liczba ocen, które przyczyniły się do wartości pola rating.
rating_scale Przydatne Skala oceniania używana w przypadku pola rating. Jeśli maksymalna ocena to 5, to rating_scale wynosi 5.
kategoria Przydatne Reprezentuje kategorię usługi.
hotel_data Przydatne Pola dotyczące konkretnego hotelu. Więcej informacji znajdziesz w sekcji Definicja HotelData.
hotel_star_class Zalecane Oficjalna klasa hotelu wyrażona w gwiazdkach. Ta wartość powinna być liczbą całkowitą z zakresu od 0 do 5. Jeśli Twój system używa wartości z połówkami gwiazdek lub wartości dziesiętnych (np. 3.5), zaokrąglij je w dół do liczby całkowitej (3). Jeśli liczba gwiazdek jest niedostępna, nieznana lub nieokreślona, podaj wartość 0. Gdy zasada ma wartość 0, w interfejsie nie będzie wyświetlana klasa gwiazdkowa hotelu.
brand_ids Przydatne 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.
opis Przydatne Szczegółowy opis obiektu.
display_address Przydatne Adres wyświetlany w interfejsie.

Wytyczne dotyczące obrazów

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

  • 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.

Obsługa wielu języków

Plik danych o interesujących miejscach umożliwia dostarczanie zlokalizowanych treści w przypadku określonych pól. Te pola są typu Text i obsługują lokalizację:

  • name
  • description
  • display_address

Aby udostępniać treści w wielu językach, musisz określić default_locale w polu i podać zlokalizowane ciągi znaków na liście localizations. Podaj wszystkie wersje językowe usługi w jednym wpisie dotyczącym ważnego miejsca. Nie dziel pojedynczej właściwości między wiele plików 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 usług w jeden plik JSON. Zalecamy skompresowanie go do jednego archiwum GZIP i przesłanie.
  • Ostrzeżenie dotyczące nieprawidłowego wzorca: nie używaj jednego pliku na usługę ani wielu plików rozdzielonych według kraju w tym samym archiwum. To podejście jest nieobsługiwane i spowoduje błędy wyodrębniania.

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 {

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

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

Przykłady

Źródło danych o ciekawych miejscach

Nazwa pliku: 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"]
      }
    }
  ]
}

Plik danych z informacjami o wielojęzycznych ważnych miejscach

Nazwa pliku: 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"]
      }
    }
  ]
}