Eine Nearby Search (New)-Anfrage verwendet einen oder mehrere Ortstypen und gibt eine Liste übereinstimmender Orte innerhalb des angegebenen Gebiets zurück. Eine Feldmaske, die einen oder mehrere Datentypen angibt, ist erforderlich. Nearby Search (New) unterstützt nur POST-Anfragen.
Mit dem API Explorer können Sie Live-Anfragen stellen, damit Sie sich mit der API und den API-Optionen vertraut machen können:
Testen!In der interaktiven Demo sehen Sie, wie „Nearby Search (New)“-Ergebnisse auf einer Karte angezeigt werden.
„Nearby Search (New)“-Anfragen
Eine „Nearby Search (New)“-Anfrage ist eine HTTP-POST-Anfrage an eine URL im folgenden Format:
https://places.googleapis.com/v1/places:searchNearby
Übergeben Sie alle Parameter im JSON-Anfragetext oder in den Headern als Teil der POST-Anfrage. Beispiel:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
„Nearby Search (New)“-Antworten
„Nearby Search (New)“ gibt ein JSON-Objekt als Antwort zurück. In der Antwort:
- Das Array
places
enthält alle übereinstimmenden Orte. - Jeder Ort im Array wird durch ein
Place
-Objekt dargestellt. Das ObjektPlace
enthält detaillierte Informationen zu einem einzelnen Ort. - Die in der Anfrage übergebene FieldMask gibt die Liste der Felder an, die im Objekt
Place
zurückgegeben werden.
Das vollständige JSON-Objekt hat das folgende Format:
{ "places": [ { object (Place) } ] }
Erforderliche Parameter
-
FieldMask
Geben Sie die Liste der Felder an, die in der Antwort zurückgegeben werden sollen. Erstellen Sie dazu eine Antwortfeldmaske. Übergeben Sie die Antwortfeldmaske an die Methode. Verwenden Sie dazu den URL-Parameter
$fields
oderfields
oder den HTTP-HeaderX-Goog-FieldMask
. Die Antwort enthält keine Standardliste mit zurückgegebenen Feldern. Wenn Sie die Feldmaske weglassen, gibt die Methode einen Fehler zurück.Die Maskierung von Feldern hat sich bewährt, um sicherzustellen, dass keine unnötigen Daten angefordert werden. So lassen sich unnötige Verarbeitungszeiten und Gebühren vermeiden.
Geben Sie eine durch Kommas getrennte Liste der Ortsdatentypen an, die zurückgegeben werden sollen. Beispielsweise können Sie den Anzeigenamen und die Adresse des Orts abrufen.
X-Goog-FieldMask: places.displayName,places.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 „Nearby Search (Basic)“ aus:
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.attributions
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.adrFormatAddress
places.name
places.subDestinations
places.types
places.utcOffsetMinutes
places.viewport
places/PLACE_ID
Verwenden Sieplaces.displayName
, um auf den Textnamen des Orts zuzugreifen.Die folgenden Felder lösen die SKU „Nearby Search (Advanced)“ aus:
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Die folgenden Felder lösen die SKU „Nearby Search (Preferred)“ aus:
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.servesBeer
, {2/3/1}/places.servesBrunch
places.servesBreakfast
places.servesCocktails
places.servesCoffee
places.servesDessert
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
Der zu durchsuchende Bereich, angegeben als Kreis, definiert durch einen Mittelpunkt und einen Radius in Metern. Der Radius muss zwischen 0,0 und 50.000,0 (einschließlich) liegen. Der Standardradius ist 0,0. Sie müssen ihn in Ihrer Anfrage auf einen Wert größer als 0,0 festlegen.
Beispiel:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Optionale Parameter
-
eingeschlossen
Geben Sie hier eine Liste von Typen aus Tabelle A an, die zum Filtern der Suchergebnisse verwendet werden. In jeder Typeinschränkungskategorie können bis zu 50 Typen angegeben werden.
Einem Ort kann nur ein einziger Haupttyp aus dem Typ Tabelle A zugeordnet sein. Der primäre Typ kann beispielsweise
"mexican_restaurant"
oder"steak_house"
sein. Verwenden SieincludedPrimaryTypes
undexcludedPrimaryTypes
, um die Ergebnisse nach dem primären Typ eines Ortes zu filtern.Ein Ort kann auch mehrere Typwerte aus dem Typ Tabelle A haben. Ein Restaurant kann beispielsweise die folgenden Typen haben:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. Verwenden SieincludedTypes
undexcludedTypes
, um die Ergebnisse in der Liste der Typen zu filtern, die mit einem Ort verknüpft sind.Wenn für eine Suche mehrere Typeinschränkungen gelten, werden nur Orte zurückgegeben, die alle Einschränkungen erfüllen. Wenn Sie beispielsweise
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
angeben, stellen die zurückgegebenen Orte"restaurant"
-bezogene Dienste bereit, werden aber nicht primär als"steak_house"
verwendet.includedTypes
Eine durch Kommas getrennte Liste der Ortstypen aus Tabelle A, nach denen gesucht werden soll. Wird dieser Parameter weggelassen, werden Orte aller Typen zurückgegeben.
excludedTypes
Eine durch Kommas getrennte Liste von Ortstypen aus Tabelle A, die von einer Suche ausgeschlossen werden sollen.
Wenn Sie in der Anfrage sowohl
includedTypes
( z. B."school"
) als auchexcludedTypes
(z. B."primary_school"
) angeben, enthält die Antwort Orte, die als"school"
, aber nicht als"primary_school"
kategorisiert sind. Die Antwort enthält Orte, die mit mindestens einem derincludedTypes
und keinem derexcludedTypes
übereinstimmen.Wenn Typen in Konflikt stehen, z. B. ein Typ, der sowohl in
includedTypes
als auch inexcludedTypes
enthalten ist, wird einINVALID_REQUEST
-Fehler zurückgegeben.includedPrimaryTypes
Eine durch Kommas getrennte Liste der primären Ortstypen aus Tabelle A, die in eine Suche aufgenommen werden sollen.
excludedPrimaryTypes
Eine durch Kommas getrennte Liste der primären Ortstypen aus Tabelle A, die von einer Suche ausgeschlossen werden sollen.
Wenn Primärtypen in Konflikt stehen, z. B. ein Typ, der sowohl in
includedPrimaryTypes
als auch inexcludedPrimaryTypes
enthalten ist, wird der FehlerINVALID_ARGUMENT
zurückgegeben. -
languageCode
Die Sprache, in der die Ergebnisse zurückgegeben werden sollen.
- Hier finden Sie eine Liste der unterstützten Sprachen. Google aktualisiert die unterstützten Sprachen häufig. Daher ist diese Liste möglicherweise nicht vollständig.
- Wenn
languageCode
nicht angegeben ist, wird standardmäßigen
verwendet. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API den FehlerINVALID_ARGUMENT
zurück. - Die API versucht, eine Adresse anzugeben, die sowohl für Nutzer als auch für Ortsansässige lesbar ist. Dazu werden Adressen in der lokalen Sprache zurückgegeben und bei Bedarf unter Berücksichtigung der bevorzugten Sprache in ein für den Nutzer lesbares Skript transkribiert. Alle übrigen Adressen werden in der bevorzugten Sprache zurückgegeben. Alle Adresskomponenten werden in derselben Sprache zurückgegeben, die aus der ersten Komponente ausgewählt wird.
- Wenn der Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die am besten passende Entsprechung.
- Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnisse, die von der API zurückgegeben werden, und auf die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen je nach Sprache unterschiedlich, z. B. Abkürzungen für Straßentypen oder Synonyme, die möglicherweise in einer Sprache gültig sind, in einer anderen jedoch nicht.
-
maxResultCount
Gibt die maximale Anzahl der Ortsergebnisse an, die zurückgegeben werden sollen. Der Wert muss zwischen 1 und 20 (Standardeinstellung) liegen.
-
rankPreference
Der zu verwendende Rankingtyp. Wenn Sie diesen Parameter nicht angeben, werden die Ergebnisse nach Beliebtheit sortiert. Folgende Werte sind möglich:
POPULARITY
(Standardeinstellung): Sortiert die Ergebnisse nach ihrer Beliebtheit.DISTANCE
: Die Ergebnisse werden in aufsteigender Reihenfolge nach ihrer Entfernung vom angegebenen Ort sortiert.
-
regionCode
Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger CLDR-Code. Es gibt keinen Standardwert.
Wenn der Ländername des Felds
formattedAddress
in der Antwort mitregionCode
übereinstimmt, wird der Ländercode informattedAddress
weggelassen. Dieser Parameter hat keine Auswirkungen aufadrFormatAddress
, das immer den Ländernamen enthält, oder aufshortFormattedAddress
, der ihn nie enthält.Die meisten CLDR-Codes entsprechen den ISO 3166-1-Codes, mit einigen Ausnahmen. So lautet beispielsweise die ccTLD des Vereinigten Königreichs „uk“ (.co.uk) und der ISO 3166-1-Code „gb“ (technisch für die Rechtspersönlichkeit „The United Kingdom of Great Britain and Northern Ireland“). Der Parameter kann sich gemäß geltendem Recht auf Ergebnisse auswirken.
Beispiele für Nearby Search (New)
Orte eines bestimmten Typs finden
Das folgende Beispiel zeigt eine „Nearby Search (New)“-Anfrage für die Anzeigenamen aller Restaurants in einem Radius von 500 Metern, der durch circle
definiert wird:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Der X-Goog-FieldMask
-Header gibt an, dass die Antwort die folgenden Datenfelder enthält: places.displayName
.
Die Antwort hat dann das folgende Format:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
Fügen Sie der Feldmaske weitere Datentypen hinzu, um zusätzliche Informationen zurückzugeben.
Fügen Sie beispielsweise places.formattedAddress,places.types,places.websiteUri
hinzu, um die Adresse, den Typ und die Webadresse des Restaurants in die Antwort aufzunehmen:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
Die Antwort hat jetzt das folgende Format:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
Orte unterschiedlicher Kategorien finden
Das folgende Beispiel zeigt eine „Nearby Search (New)“-Anfrage für die Anzeigenamen aller Minimarkt und Spirituosengeschäfte im Umkreis von 1.000 m um den angegebenen circle
:
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearbyIn diesem Beispiel werden der Feldmaske
places.primaryType
und places.types
hinzugefügt, sodass die Antwort Typinformationen zu jedem Ort enthält. So kann der entsprechende Ort aus den Ergebnissen leichter ausgewählt werden.
Ortstyp aus der Suche ausschließen
Das folgende Beispiel zeigt eine „Nearby Search (New)“-Anfrage für alle Orte des Typs "school"
, mit Ausnahme aller Orte vom Typ "primary_school"
, wobei die Ergebnisse nach Entfernung sortiert werden:
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Nach allen Orten in der Nähe eines Gebiets suchen, nach Entfernung sortieren
Das folgende Beispiel zeigt eine „Nearby Search (New)“-Anfrage für Orte in der Nähe eines Punkts in der Innenstadt von San Francisco. In diesem Beispiel fügen Sie den Parameter rankPreference
ein, um die Ergebnisse nach Entfernung zu sortieren:
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Jetzt testen
Mit dem API 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 aus.
- Erweitern Sie optional Standardparameter anzeigen und legen Sie den Parameter
fields
auf die Feldmaske fest. - Optional können Sie den Anfragetext bearbeiten.
- Klicken Sie auf die Schaltfläche Execute (Ausführen). Wählen Sie im Pop-up-Fenster das Konto aus, das Sie für die Anfrage verwenden möchten.
Klicken Sie im Bereich „API Explorer“ auf das Symbol zum Maximieren (), um das API Explorer-Fenster zu maximieren.