Szczegóły miejsca (nowość)

Wprowadzenie

Gdy uzyskasz identyfikator miejsca, możesz poprosić o więcej informacji o konkretnym obiekcie lub punkcie orientacyjnym, wysyłając żądanie Szczegóły miejsca (nowe). Żądanie Place Details (New) zwraca bardziej szczegółowe informacje o wskazanym miejscu takie jak pełny adres, numer telefonu, oceny i opinie użytkowników.

Identyfikator miejsca można uzyskać na wiele sposobów. Możesz użyć:

• Wyszukiwanie tekstowe (nowość) lub wyszukiwanie w pobliżu (nowość)
• Geocoding API
• Routes API
• Address Validation API
• Autouzupełnianie (nowość)

Narzędzie API Explorer umożliwia wysyłanie żądań w czasie rzeczywistym, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami:

Prośby o informacje o miejscu (nowe)

Żądanie szczegółów miejsca (nowe) to żądanie HTTP GET w formacie:

https://places.googleapis.com/v1/places/PLACE_ID

Przekaż wszystkie parametry jako parametry adresu URL lub w nagłówkach w ramach żądania GET. Na przykład:

https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEY

Możesz też użyć polecenia curl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Odpowiedzi dotyczące informacji o miejscu (nowe)

Szczegóły miejsca (nowe) zwracają obiekt JSON jako odpowiedź. W odpowiedzi:

• Odpowiedź jest reprezentowana przez obiekt Place. Obiekt Place zawiera szczegółowe informacje o miejscu.
• FieldMask przekazany w żądaniu określa listę pól zwracanych w obiekcie Place.

Pełny obiekt JSON ma postać:

{
  "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g",
  "displayName": {
    "text": "Trinidad"
  }
  ...
}

Wymagane parametry

• FieldMask

  Określ listę pól, które mają być zwracane w odpowiedzi, tworząc maskę pola odpowiedzi. Przekaż maskę pola odpowiedzi do metody za pomocą parametru adresu URL $fields lub fields albo za pomocą nagłówka HTTP X-Goog-FieldMask. W odpowiedzi nie ma domyślnej listy zwracanych pól. Jeśli pominiesz maskę pola, metoda zwróci błąd.

  Maskowanie pól to dobra praktyka projektowania, która pozwala uniknąć żądania niepotrzebnych danych, co z kolei pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat.

  Podaj rozdzieloną przecinkami listę typów danych o miejscach, które mają zostać zwrócone. Na przykład, aby pobrać nazwę wyświetlaną i adres miejsca.

  X-Goog-FieldMask: displayName,formattedAddress

  Użyj *, aby pobrać wszystkie pola.

  X-Goog-FieldMask: *

  Określ co najmniej jedno z tych pól:

  • Te pola wywołują SKU Place Details Essentials IDs Only:

    attributions
id
name^*
    photos
    

    ^* Pole name zawiera nazwę zasobu miejsca w formacie: places/PLACE_ID. Aby uzyskać tekstową nazwę miejsca, w przypadku wersji Pro wyślij żądanie dotyczące pola displayName.

  • Te pola wywołują podstawowy SKU szczegółów miejsca:

    addressComponents
addressDescriptor^*
    adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
    
    ^* Opisy adresów są ogólnie dostępne dla klientów w Indiach, a w innych krajach są w fazie eksperymentalnej.
    
    

  • Te pola wywołują kod SKU Szczegóły miejsca Pro:

    accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
utcOffsetMinutes
    
    

  • Te pola wywołują kod SKU Szczegóły miejsca w wersji Enterprise:

    currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
userRatingCount
websiteUri

  • Te pola wywołują kod SKU informacji o miejscu Enterprise + Atmosphere:

    allowsDogs
curbsidePickup
delivery
dineIn
editorialSummary
evChargeAmenitySummary
evChargeOptions
fuelOptions
generativeSummary
goodForChildren
goodForGroups
goodForWatchingSports
liveMusic
menuForChildren
neighborhoodSummary
parkingOptions
paymentOptions
outdoorSeating
reservable
restroom
reviews
reviewSummary
routingSummaries^*
    servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
    
    ^* Tylko wyszukiwanie tekstowe i wyszukiwanie w pobliżu

• placeId

  Identyfikator tekstowy, który jednoznacznie identyfikuje miejsce i jest zwracany przez wyszukiwanie tekstowe (nowe) lub wyszukiwanie w pobliżu (nowe). Więcej informacji o identyfikatorach miejsc znajdziesz w omówieniu identyfikatorów miejsc.

  Ciąg znaków places/PLACE_ID jest też nazywany nazwą zasobu miejsca. W odpowiedzi na żądanie szczegółów miejsca (nowe), wyszukiwania w pobliżu (nowe) i wyszukiwania tekstowego (nowe) ten ciąg znaków znajduje się w polu name odpowiedzi. Samodzielny identyfikator miejsca znajduje się w polu id w odpowiedzi.

  .

Parametry opcjonalne

• languageCode

  Język, w którym mają być zwracane wyniki.

  • Zobacz listę obsługiwanych języków. Google często aktualizuje listę obsługiwanych języków, więc może ona nie być kompletna.
  • Jeśli nie podasz wartości languageCode, interfejs API domyślnie użyje wartości en. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błąd INVALID_ARGUMENT.
  • Interfejs API stara się podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i mieszkańców. Aby to osiągnąć, zwraca adresy w języku lokalnym, a w razie potrzeby transliteruje je na pismo czytelne dla użytkownika, uwzględniając preferowany język. Wszystkie pozostałe adresy są zwracane w preferowanym języku. Wszystkie komponenty adresu są zwracane w tym samym języku, który jest wybierany na podstawie pierwszego komponentu.
  • Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API użyje najbliższego dopasowania.
  • Preferowany język ma niewielki wpływ na zestaw wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność, w jakiej są one zwracane. Geokoder interpretuje skróty w różny sposób w zależności od języka, np. skróty typów ulic lub synonimy, które mogą być prawidłowe w jednym języku, ale nie w innym.

• regionCode

  Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowy kod CLDR. Nie ma wartości domyślnej.

  Jeśli nazwa kraju w polu formattedAddress w odpowiedzi pasuje do regionCode, kod kraju jest pomijany w polu formattedAddress. Ten parametr nie ma wpływu na parametr adrFormatAddress, który zawsze zawiera nazwę kraju, ani na parametr shortFormattedAddress, który nigdy jej nie zawiera.

  Większość kodów CLDR jest identyczna z kodami ISO 3166-1, z kilkoma istotnymi wyjątkami. Na przykład krajowa domena najwyższego poziomu Zjednoczonego Królestwa to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”). W zależności od obowiązujących przepisów parametr może wpływać na wyniki.

• sessionToken

  Tokeny sesji to wygenerowane przez użytkownika ciągi znaków, które śledzą wywołania Autouzupełniania (nowego) jako „sesje”. Autouzupełnianie (nowe) używa tokenów sesji do grupowania faz zapytania i wyboru miejsca w wyszukiwaniu autouzupełniania użytkownika w osobnej sesji na potrzeby rozliczeń. Tokeny sesji są przekazywane do wywołań Place Details (New) po wywołaniach Autocomplete (New). Więcej informacji znajdziesz w sekcji Tokeny sesji.

Przykład Informacji o miejscu (nowych)

Ten przykład wysyła żądanie szczegółów miejsca za pomocą parametru placeId:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Zwróć uwagę, że nagłówek X-Goog-FieldMask określa, że odpowiedź zawiera te pola danych: id,displayName. Odpowiedź ma wtedy postać:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

Dodaj do maski pola więcej typów danych, aby zwracać dodatkowe informacje. Na przykład dodaj formattedAddress,plusCode, aby uwzględnić adres i kod plus w odpowiedzi:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw

Odpowiedź ma teraz postać:

{
  "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "plusCode": {
    "globalCode": "849VCWC7+RW",
    "compoundCode": "CWC7+RW Mountain View, CA, USA"
  },
  "displayName": {
    "text": "Googleplex",
    "languageCode": "en"
  }
}

Pobieranie deskryptorów adresu

Deskryptory adresów zawierają informacje o lokalizacji miejsca, w tym o pobliskich punktach orientacyjnych i obszarach.

Poniższy przykład pokazuje żądanie szczegółów miejsca (nowe) dotyczące domu towarowego w centrum handlowym w San Jose. W tym przykładzie w masce pola uwzględniasz addressDescriptors:

  curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \
  -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
  -H "X-Goog-FieldMask: name,displayName,addressDescriptor"

Odpowiedź zawiera miejsce określone w żądaniu, listę pobliskich punktów orientacyjnych i ich odległość od tego miejsca oraz listę obszarów i ich relację do tego miejsca:

  {
    "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
    "displayName": {
      "text": "Macy's",
      "languageCode": "en"
    },
    "addressDescriptor": {
      "landmarks": [
        {
          "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "food",
            "movie_theater",
            "point_of_interest",
            "restaurant",
            "shoe_store",
            "shopping_mall",
            "store"
          ],
          "spatialRelationship": "WITHIN",
          "straightLineDistanceMeters": 220.29175
        },
        {
          "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
          "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
          "displayName": {
            "text": "Nordstrom",
            "languageCode": "en"
          },
          "types": [
            "clothing_store",
            "department_store",
            "establishment",
            "point_of_interest",
            "shoe_store",
            "store"
          ],
          "straightLineDistanceMeters": 329.45178
        },
        {
          "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE",
          "displayName": {
            "text": "Monroe Parking Garage",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "parking",
            "point_of_interest"
          ],
          "straightLineDistanceMeters": 227.05153
        },
        {
          "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM",
          "displayName": {
            "text": "Studios Inn by Daiwa Living California Inc.",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "lodging",
            "point_of_interest",
            "real_estate_agency"
          ],
          "straightLineDistanceMeters": 299.9955
        },
        {
          "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
          "displayName": {
            "text": "Din Tai Fung",
            "languageCode": "en"
          },
          "types": [
            "establishment",
            "food",
            "point_of_interest",
            "restaurant"
          ],
          "straightLineDistanceMeters": 157.70943
        }
      ],
      "areas": [
        {
          "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
          "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
          "displayName": {
            "text": "Westfield Valley Fair",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        },
        {
          "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
          "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
          "displayName": {
            "text": "Valley Fair",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        },
        {
          "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
          "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
          "displayName": {
            "text": "Central San Jose",
            "languageCode": "en"
          },
          "containment": "WITHIN"
        }
      ]
    }
  }

Wypróbuj

Narzędzie APIs Explorer umożliwia wysyłanie przykładowych żądań, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami.

1. Po prawej stronie strony kliknij ikonę interfejsu API api.

2. Opcjonalnie edytuj parametry żądania.

3. Kliknij przycisk Wykonaj. W oknie dialogowym wybierz konto, z którego chcesz wysłać prośbę.

4. W panelu APIs Explorer kliknij ikonę pełnego ekranu fullscreen, aby rozwinąć okno narzędzia.