Einführung
Sobald Sie eine Orts-ID haben, können Sie weitere Details zu einem bestimmten Unternehmen oder Ort von Interesse anfordern, indem Sie eine „Place Details (New)“- Anfrage stellen. Bei einer „Place Details (New)“-Anfrage werden umfassendere Informationen zum angegebenen Ort zurückgegeben, z. B. die vollständige Adresse, Telefonnummer, Nutzerbewertungen und Rezensionen.
Es gibt viele Möglichkeiten, eine Orts-ID zu erhalten. Sie können Folgendes angeben:
- Text Search (New) oder Nearby Search (New)
- Geocoding API
- Routes API
- Address Validation API
- Automatische Vervollständigung (New)
Mit dem APIs Explorer können Sie Live-Anfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen:
„Place Details (New)“-Anfragen
Eine „Place Details (New)“-Anfrage ist eine HTTP-GET-Anfrage im folgenden Format:
https://places.googleapis.com/v1/places/PLACE_ID
Übergeben Sie alle Parameter als URL-Parameter oder in Headern als Teil der GET-Anfrage. Beispiel:
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEYOder in einem curl-Befehl:
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
„Place Details (New)“-Antworten
„Place Details (New)“ gibt ein JSON-Objekt als Antwort zurück. Die Antwort sieht so aus:
- Die Antwort wird durch ein
PlaceObjekt dargestellt. DasPlaceObjekt enthält detaillierte Informationen zum Ort. - Die in der Anfrage übergebene FieldMask gibt die Liste der Felder an,
die im
PlaceObjekt zurückgegeben werden.
Das vollständige JSON-Objekt hat das folgende Format:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
Erforderliche Parameter
-
FieldMask
Geben Sie die Liste der Felder an, die in der Antwort zurückgegeben werden sollen, indem Sie eine Feldmaske für die Antwort erstellen. Übergeben Sie die Feldmaske für die Antwort mit dem URL-Parameter
$fieldsoderfields, oder mit dem HTTP-HeaderX-Goog-FieldMaskan die Methode. Es gibt keine Standardliste der in der Antwort zurückgegebenen Felder. Wenn Sie die Feldmaske weglassen, gibt die Methode einen Fehler zurück.Mit der Maskierung von Feldern lässt sich verhindern, dass unnötige Daten angefordert werden was wiederum hilft, unnötige Verarbeitungszeiten und Gebühren zu vermeiden.
Geben Sie eine durch Kommas getrennte Liste der Ortsdatentypen an, die zurückgegeben werden sollen. Beispiel: So rufen Sie den Anzeigenamen und die Adresse des Ortes ab.
X-Goog-FieldMask: displayName,formattedAddress
Verwenden Sie
*, um alle Felder abzurufen.X-Goog-FieldMask: *
Geben Sie eines oder mehrere der folgenden Felder an:
Die folgenden Felder lösen die SKU „Place Details Essentials IDs Only“ aus:
attributions
id
moved_place
moved_place_id
name*
photos
* Das Feld
nameenthält den Ressourcennamen des Orts im folgenden Format:places/PLACE_ID. Wenn Sie den Textnamen des Ortes abrufen möchten, fordern Sie das FelddisplayNamein der Pro-SKU an.Die folgenden Felder lösen die SKU „Place Details Essentials“ aus:
addressComponents
addressDescriptor*
adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
* Adressdeskriptoren sind für Kunden in Indien allgemein verfügbar und werden an anderen Orten getestet.
Die folgenden Felder lösen die SKU „Place Details Pro“ aus:
accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
openingDate
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
timeZone
utcOffsetMinutes
Die folgenden Felder lösen die SKU „Place Details Enterprise“ aus:
currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
transitStation
userRatingCount
websiteUriDie folgenden Felder lösen die SKU „Place Details Enterprise + Atmosphere“ aus:
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
* Nur Textsuche und Suche in der Nähe
-
placeId
Eine Kennung in Textform, die einen Ort eindeutig definiert und von einer Text Search (New) oder Nearby Search (New) zurückgegeben wird. Weitere Informationen finden Sie in der Übersicht zur Orts-ID.
Der String
places/PLACE_IDwird auch als Ressourcenname des Orts bezeichnet. In der Antwort auf eine „Place Details (New)“-, „Nearby Search (New)“ und „Text Search (New)“-Anfrage ist dieser String im Feldnameder Antwort enthalten. Die eigenständige Orts-ID ist imidFeld der Antwort enthalten.
Optionale Parameter
languageCode
Die Sprache, in der die Ergebnisse zurückgegeben werden sollen.
- Hier finden Sie eine Liste der unterstützten Sprachen. Die unterstützten Sprachen werden regelmäßig von Google aktualisiert sodass diese Liste möglicherweise nicht vollständig ist.
-
Wenn
languageCodenicht angegeben wird, verwendet die API standardmäßigen. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API einenINVALID_ARGUMENTFehler zurück. - Die API versucht, eine Straßenadresse bereitzustellen, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Zu diesem Zweck werden Straßen adressen in der lokalen Sprache zurückgegeben, bei Bedarf in ein für den Nutzer lesbares Schriftsystem transliteriert und die bevorzugte Sprache berücksichtigt. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die anhand der ersten Komponente ausgewählt wird.
- Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die nächstbeste Übereinstimmung.
- Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnisse, die die API zurückgibt, und auf die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen je nach Sprache unterschiedlich, z. B. die Abkürzungen für Straßentypen oder Synonyme, die in einer Sprache gültig sein können, in einer anderen jedoch nicht.
regionCode
Der Regionscode, der zum Formatieren der Antwort verwendet wird, angegeben als CLDR-Code mit zwei Zeichen. Es gibt keinen Standardwert.
Wenn der Ländername des Felds
formattedAddressin der Antwort mit demregionCodeübereinstimmt, wird der Ländercode ausformattedAddressentfernt. Dieser Parameter hat keine Auswirkungen aufadrFormatAddress, das immer den Ländernamen enthält, oder aufshortFormattedAddress, das ihn nie enthält.Die meisten CLDR-Codes sind mit den ISO 3166-1-Codes identisch, es gibt jedoch einige bemerkenswerte Ausnahmen. So lautet beispielsweise die ccTLD des Vereinigten Königreichs ist „uk“ (.co.uk), der ISO 3166-1-Code dagegen „gb“ (technisch für die Einheit „Vereinigtes Königreich Großbritannien und Nordirland“). Der Parameter kann sich je nach geltendem Recht auf die Ergebnisse auswirken.
-
sessionToken
Sitzungstokens sind von Nutzern generierte Strings, mit denen „Automatische Vervollständigung (New)“-Aufrufe als "Sitzungen" erfasst werden. In „Automatische Vervollständigung (New)“ werden Sitzungstokens verwendet, um die Abfrage- und Ortsauswahlphasen einer Nutzeranfrage zur automatischen Vervollständigung zu Abrechnungszwecken zu einer separaten Sitzung zusammenzufassen. Sitzungstokens werden an „Place Details (New)“ Aufrufe übergeben, die auf „Automatische Vervollständigung (New)“-Aufrufe folgen. Weitere Informationen finden Sie unter Sitzungstokens.
Beispiel für „Place Details (New)“
Im folgenden Beispiel werden die Details eines Ortes anhand der placeId angefordert:
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
Beachten Sie, dass der X-Goog-FieldMask Header angibt, dass die
Antwort
die folgenden Datenfelder enthält: id,displayName.
Die Antwort hat dann das folgende Format:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" } }
Fügen Sie der Feldmaske weitere Datentypen hinzu, um zusätzliche Informationen zurückzugeben.
Fügen Sie beispielsweise formattedAddress,plusCode hinzu, um die
Adresse und den Plus Code in die
Antwort aufzunehmen:
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
Die Antwort hat jetzt das folgende Format:
{ "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" } }
Adressdeskriptoren abrufen
Adressdeskriptoren enthalten relationale Informationen zum Standort eines Ortes, einschließlich nahe gelegener Sehenswürdigkeiten und enthaltener Gebiete.
Das folgende Beispiel zeigt eine „Place Details (New)“-Anfrage für ein Kaufhaus
in einem Einkaufszentrum in San Jose. In diesem Beispiel fügen Sie addressDescriptors
in die Feldmaske ein:
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"
Die Antwort enthält den in der Anfrage angegebenen Ort, eine Liste der nahe gelegenen Sehenswürdigkeiten und ihre Entfernung zum Ort sowie eine Liste der Gebiete und ihre Beziehung zum Ort:
{ "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" } ] } }
Ortsdetails für einen umgezogenen Ort abrufen
Wenn ein Ort, auf den in Ihrer App verwiesen wird, umgezogen ist, können Sie die
movedPlace und movedPlaceId Felder verwenden, um die Details des neuen Ortes abzurufen.
Für Orte, die dauerhaft geschlossen sind, gibt „Place Details (New)“ CLOSED_PERMANENTLY im
businessStatus Feld zurück und lässt die Felder movedPlace und
movedPlaceId im Antworttext weg.
Für Orte, die an einen neuen Standort umgezogen sind, gibt „Place Details (New)“ CLOSED_PERMANENTLY im
businessStatus Feld zurück und gibt den neuen Standort in den movedPlace und
movedPlaceId Feldern des Antworttexts zurück.
Für Orte, die nicht umgezogen sind, gibt „Place Details (New)“
movedPlace oder movedPlaceId nicht im Antworttext zurück.
Im folgenden Beispiel werden Ortsinformationen zu Marche IGA St-Canut in Quebec, Kanada, angefordert:
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
Die Anfrage gibt die folgende Antwort zurück:
{ "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ", "businessStatus": "CLOSED_PERMANENTLY", "displayName": { "text": "Marche IGA St-Canut", "languageCode": "en" }, "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ", "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ" }
Wenn Sie Details zum neuen Ort anfordern möchten, verwenden Sie den Ressourcennamen des Orts im Feld movedPlace
in einer neuen „Place Details (New)“-Anfrage.
Für Orte, die mehrmals umgezogen sind, sind möglicherweise mehrere verkettete „Place Details (New)“-Anfragen erforderlich, um Details zum aktuellen Standort
zu erhalten. Die movedPlace und
movedPlaceId Felder eines Ortsergebnisses verweisen nur auf den nächsten Standort, nicht auf den letzten
bekannten Standort. Ein Ort befindet sich an seinem aktuellen Standort , wenn bei einer „Place Details (New)“-Anfrage
die Felder movedPlace und movedPlaceId im Antworttext weggelassen werden.
Nach Unternehmen suchen, die in Zukunft eröffnet werden
Sie können Details zu Unternehmen anfordern, die voraussichtlich in Zukunft eröffnet werden.
Bei der Nearby Search (New) wird das openingDate Feld ausgefüllt, wenn das voraussichtliche
Eröffnungsdatum mindestens den Monat enthält und weniger als 90 Tage entfernt ist.
Das folgende Beispiel zeigt eine „Nearby Search (New)“-Anfrage für ein Unternehmen, das in Zukunft in New Meadows, Idaho, eröffnet wird:
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"
Die Antwort enthält den Unternehmensstatus und das voraussichtliche Eröffnungsdatum des Ortes:
{ "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "openingDate": { "year": 2026, "month": 4, "day": 15 } }
Informationen zu Bahnhöfen und Haltestellen abrufen
Mit „Place Details (New)“ können Sie Informationen zu Bahnhöfen und Haltestellen abrufen. Der Antworttext enthält Informationen zum Bahnhof oder zur Haltestelle, einschließlich des Namens, der angeschlossenen Verkehrsbetriebe und der Linien, die den Bahnhof oder die Haltestelle bedienen. Außerdem enthält die Antwort ein Fahrzeugsymbol und Farben, mit denen Sie die Informationen zum Bahnhof oder zur Haltestelle anzeigen können.
Das folgende Beispiel zeigt eine Anfrage nach Informationen zum Bahnhof 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"
Der Antworttext enthält Informationen zu jedem Bahnhof oder jeder Haltestelle im Radius, zu den Linien, die den Bahnhof oder die Haltestelle bedienen, zu Warnmeldungen von Verkehrsbetrieben an dieser Haltestelle und zu Abfahrtsinformationen:
{ "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 } ... ] } }
Testen!
Mit dem APIs Explorer können Sie Beispielanfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen.
Wählen Sie rechts auf der Seite das API-Symbol api aus.
Optional können Sie die Anfrageparameter bearbeiten.
Wählen Sie die Schaltfläche Ausführen aus. Wählen Sie im Dialogfeld das Konto aus, das Sie für die Anfrage verwenden möchten.
Wählen Sie im APIs Explorer-Bereich das Symbol für den Vollbildmodus fullscreen aus, um das APIs Explorer-Fenster zu maximieren.