Wprowadzenie
Gdy masz identyfikator miejsca, możesz poprosić o więcej informacji o konkretnym obiekcie lub punkcie orientacyjnym, wysyłając żądanie informacji o miejscu (nowe). Żądanie informacji o miejscu (nowe) 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ć:
- Wyszukiwania tekstowego (nowe) lub wyszukiwania w pobliżu (nowe)
- Geocoding API
- Routes API
- Address Validation API
- Autouzupełniania (nowe)
Narzędzie APIs Explorer umożliwia wysyłanie żądań w czasie rzeczywistym, dzięki czemu możesz zapoznać się z interfejsem API i jego opcjami:
Żądania informacji o miejscu (nowe)
Żądanie informacji o miejscu (nowe) to żądanie HTTP GET w postaci:
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_KEYLub w poleceniu 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 na żądania informacji o miejscu (nowe)
Informacje o miejscu (nowe) zwracają obiekt JSON jako odpowiedź. W odpowiedzi:
- Odpowiedź jest reprezentowana przez a
Placeobiekt. ObiektPlacezawiera szczegółowe informacje o miejscu. - Pole FieldMask przekazane 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
Aby określić listę pól, które mają zostać zwrócone w odpowiedzi, utwórz maskę pola odpowiedzi. Przekaż maskę pola odpowiedzi do metody, używając parametru adresu URL
$fieldslubfields, albo nagłówka HTTPX-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 pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat.
Określ rozdzieloną przecinkami listę typów danych o miejscu, które mają zostać zwrócone. Na przykład, aby pobrać nazwę wyświetlaną i adres miejsca.
X-Goog-FieldMask: displayName,formattedAddress
Aby pobrać wszystkie pola, użyj znaku
*.X-Goog-FieldMask: *
Określ co najmniej 1 z tych pól:
Te pola aktywują jednostkę SKU Places API – informacje o miejscu – Essentials (tylko identyfikatory):
attributions
id
moved_place
moved_place_id
name*
photos
* Pole
namezawiera nazwę zasobu miejsca w postaci:places/PLACE_ID. Aby uzyskać tekstową nazwę miejsca, poproś o poledisplayNamew jednostce SKU Pro.Te pola aktywują jednostkę SKU Places API – informacje o miejscu – Essentials:
addressComponents
addressDescriptor*
adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
* Deskryptory adresu są ogólnie dostępne dla klientów w Indiach, a w innych krajach są w fazie eksperymentów.
Te pola aktywują jednostkę SKU Places API – informacje o miejscu – Pro:
accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
openingDate
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
timeZone
utcOffsetMinutes
Te pola aktywują jednostkę SKU Places API – informacje o miejscu – Enterprise:
currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
transitStation
userRatingCount
websiteUriTe pola aktywują jednostkę SKU Places API – informacje o miejscu – Enterprise + atmosfera:
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
Tekstowy identyfikator, 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 artykule Omówienie identyfikatorów miejsc.
Ciąg znaków
places/PLACE_IDjest też nazywany nazwą zasobu miejsca. W odpowiedzi na żądanie informacji o miejscu (nowe), wyszukiwania w pobliżu (nowe) i wyszukiwania tekstowego (nowe) żądanie, ten ciąg znaków znajduje się w polunameodpowiedzi. Samodzielny identyfikator miejsca znajduje się w poluidodpowiedzi.
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ć wyczerpująca.
-
Jeśli nie podasz parametru
languageCode, interfejs API domyślnie użyje językaen. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błądINVALID_ARGUMENT. - Interfejs API dokłada wszelkich starań, aby podać adres ulicy, który jest czytelny zarówno dla użytkownika, jak i dla mieszkańców. Aby to osiągnąć, zwraca adresy ulic w języku lokalnym, w razie potrzeby transliterowane na skrypt czytelny dla użytkownika, z uwzględnieniem preferowanego języka. Wszystkie inne 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 inaczej interpretuje skróty 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 dwuznakowa wartość kodu CLDR. Nie ma wartości domyślnej.
Jeśli nazwa kraju w polu
formattedAddressw odpowiedzi jest zgodna zregionCode, kod kraju jest pomijany wformattedAddress. Ten parametr nie ma wpływu naadrFormatAddress, który zawsze zawiera nazwę kraju ani nashortFormattedAddress, 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 ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”). Parametr może wpływać na wyniki na podstawie obowiązującego prawa.
-
sessionToken
Tokeny sesji to generowane przez użytkownika ciągi znaków, które śledzą wywołania autouzupełniania (nowe) jako "sesje." Autouzupełnianie (nowe) używa tokenów sesji do grupowania fazy zapytania i wyboru miejsca w ramach wyszukiwania z autouzupełnianiem w oddzielną sesję na potrzeby rozliczeń. Tokeny sesji są przekazywane do wywołań informacji o miejscu (nowe) , które następują po wywołaniach autouzupełniania (nowe). Więcej informacji znajdziesz w artykule Tokeny sesji.
Przykład informacji o miejscu (nowe)
Ten przykład ilustruje, jak poprosić o informacje o miejscu 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
Pamiętaj, że nagłówek X-Goog-FieldMask określa, że odpowiedź zawiera następujące pola danych: id,displayName.
Odpowiedź ma wtedy postać:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" } }
Aby zwrócić dodatkowe informacje, dodaj do maski pola więcej typów danych.
Na przykład dodaj formattedAddress,plusCode, aby w odpowiedzi uwzględnić adres i kod Plus Code:
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 adresu zawierają informacje o relacjach między lokalizacją miejsca, w tym o pobliskich punktach orientacyjnych i obszarach.
Ten przykład ilustruje żądanie informacji o miejscu (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 miejsca oraz listę obszarów i ich relację do 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" } ] } }
Pobieranie informacji o miejscu, które zostało przeniesione
Jeśli miejsce, do którego odwołuje się Twoja aplikacja, zostało przeniesione, możesz użyć pól
movedPlace i movedPlaceId, aby uzyskać informacje o nowym miejscu.
W przypadku miejsc zamkniętych na stałe informacje o miejscu (nowe) zwracają CLOSED_PERMANENTLY w polu
businessStatus i pomijają pola movedPlace i
movedPlaceId w treści odpowiedzi.
W przypadku miejsc, które zostały przeniesione do nowej lokalizacji, informacje o miejscu (nowe) zwracają CLOSED_PERMANENTLY w polu
businessStatus oraz nową lokalizację w polach movedPlace i
movedPlaceId w treści odpowiedzi.
W przypadku miejsc, które nie zostały przeniesione, informacje o miejscu (nowe) nie zwracają
movedPlace ani movedPlaceId w treści odpowiedzi.
Ten przykład ilustruje, jak poprosić o informacje o miejscu Marche IGA St-Canut w Quebecu w Kanadzie:
curl -X GET -H 'Content-Type: application/json' \ -H 'x-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: id,displayName,businessStatus,movedPlace,movedPlaceId' \ https://places.googleapis.com/v1/places/ChIJUfQdGInVzkwRzAjmjzWB7CQ
Żądanie zwraca tę odpowiedź:
{ "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ", "businessStatus": "CLOSED_PERMANENTLY", "displayName": { "text": "Marche IGA St-Canut", "languageCode": "en" }, "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ", "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ" }
Aby poprosić o informacje o nowym miejscu, użyj nazwy zasobu miejsca w polu movedPlace w nowym żądaniu informacji o miejscu (nowe).
W przypadku miejsc, które zostały przeniesione kilka razy, uzyskanie informacji o bieżącej lokalizacji
może wymagać kilku połączonych żądań informacji o miejscu (nowe). Pola movedPlace i
movedPlaceId w wyniku dotyczącym miejsca wskazują tylko następną lokalizację, a nie ostatnią
znaną lokalizację. Miejsce znajduje się w bieżącej lokalizacji , jeśli żądanie informacji o miejscu (nowe)
pomija pola movedPlace i movedPlaceId w treści odpowiedzi.
Znajdowanie firm, które zostaną otwarte w przyszłości
Możesz poprosić o informacje o firmach, które mają zostać otwarte w przyszłości.
Wyszukiwanie w pobliżu (nowe) wypełni pole openingDate, jeśli przewidywana
data otwarcia obejmuje co najmniej miesiąc i jest oddalona o mniej niż 90 dni.
Ten przykład ilustruje żądanie wyszukiwania w pobliżu (nowe) dotyczące firmy, która zostanie otwarta w przyszłości w New Meadows w stanie Idaho:
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,businessStatus,openingDate" \ "https://places.googleapis.com/v1/places/ChIJp1-VoKWJplQRMz8g-7Wa3Do"
Odpowiedź zawiera stan firmy i przewidywaną datę otwarcia:
{ "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "openingDate": { "year": 2026, "month": 4, "day": 15 } }
Pobieranie informacji o stacji transportu publicznego
Aby uzyskać informacje o stacjach transportu publicznego, możesz użyć informacji o miejscu (nowe). Treść odpowiedzi zawiera informacje o stacji, w tym jej nazwę, powiązane z nią agencje transportu publicznego i linie transportu publicznego obsługujące stację. Dodatkowo odpowiedź zawiera ikonę pojazdu i kolory, których możesz użyć do wyświetlania informacji o stacji transportu publicznego.
Ten przykład ilustruje żądanie informacji o stacji transportu publicznego Grand Central Station:
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,transitStation" \ "https://places.googleapis.com/v1/places/ChIJLVaKiQFZwokRgcybX3K6Pzg"
Treść odpowiedzi zawiera informacje o każdej stacji w promieniu, liniach obsługiwanych przez stację, alertach wydanych przez agencje transportu publicznego na tym przystanku oraz informacje o odjazdach:
{ "id": "ChIJLVaKiQFZwokRgcybX3K6Pzg", "displayName": { "text": "Grand Central", "languageCode": "en" }, "transitStation": { "displayName": { "text": "Grand Central", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "MTA New York City Transit", "languageCode": "en" }, "url": "http://www.mta.info/", "lines": [ { "id": "ChIJ420yFwBZwokR903kVZLSsFc", "vehicleType": "SUBWAY", "displayName": { "text": "42 St Shuttle", "languageCode": "en" }, "shortDisplayName": { "text": "S", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#808183", "url": "https://www.mta.info/schedules/subway/42-st-shuttle", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/S.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } }, { "id": "ChIJDdd_uEdfwokRHbLvWrdBdDM", "vehicleType": "SUBWAY", "displayName": { "text": "5 Train (Lexington Av Express)", "languageCode": "en" }, "shortDisplayName": { "text": "5 Line", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#00933C", "url": "https://www.mta.info/schedules/subway/5-train", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/5.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } } ... ] }, { "displayName": { "text": "MTA", "languageCode": "en" }, "url": "https://new.mta.info/", "lines": [ { "id": "ChIJcwVpzKpZwokR24EBeh8arww", "vehicleType": "BUS", "displayName": { "text": "United Nations - W 42 St Pier", "languageCode": "en" }, "shortDisplayName": { "text": "M42", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#1D59B3", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg" } } ] }, { "displayName": { "text": "Long Island Rail Road", "languageCode": "en" }, "url": "http://www.mta.info/lirr", "lines": [ { "id": "ChIJv9m8uWM56IkRUcVBQ6Q_In0", "vehicleType": "HEAVY_RAIL", "displayName": { "text": "Ronkonkoma Branch", "languageCode": "en" }, "shortDisplayName": { "text": "LIRR", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#A626AA", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg" } } ... ] } ], "stops": [ { "id": "ChIJRcemlf1YwokRhFqqw5jKBFM", "stopCode": { "text": "GCT" }, "location": { "latitude": 40.755161, "longitude": -73.975456 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJ57l2zANZwokRD1pyhuwpfKY", "signageText": { "text": "34 St-Hudson Yards & Main St-Flushing, Queens, 7", "languageCode": "en" }, "location": { "latitude": 40.750983, "longitude": -73.9750686 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJoVXJgQFZwokR1yzq_WVuEuc", "displayName": { "text": "E 42 St/Park Av", "languageCode": "en" }, "location": { "latitude": 40.7518199, "longitude": -73.9771918 }, "wheelchairAccessibleEntrance": true } ... ] } }
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.
Po prawej stronie strony kliknij ikonę interfejsu API api.
Opcjonalnie edytuj parametry żądania.
Kliknij przycisk Wykonaj. W oknie dialogowym wybierz konto, którego chcesz użyć do wysłania żądania.
W panelu APIs Explorer kliknij ikonę pełnego ekranu fullscreen, aby rozwinąć okno APIs Explorer.