Eine Nearby Search (Neu) nimmt einen oder mehrere Ortstypen an und gibt eine Liste übereinstimmender Orte innerhalb der angegebenen Bereich enthält. 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:
Testen!Probieren Sie die interaktive Demo, um die Ergebnisse von „Nearby Search (New)“ auf einer Karte zu sehen.
„Nearby Search (New)“-Anfragen
Eine „Nearby Search (New)“-Anfrage ist eine HTTP POST-Anfrage an eine URL im Formular:
https://places.googleapis.com/v1/places:searchNearby
Übergeben Sie alle Parameter im JSON-Anfragetext oder in Headern als Teil des 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 eine <ph type="x-smartling-placeholder"></ph> JSON-Objekt als Antwort an. In der Antwort:
- Das Array
places
enthält alle übereinstimmenden Orte. - Jeder Ort im Array wird durch einen
Place
-Objekt enthält. DasPlace
-Objekt enthält detaillierte Informationen zu einem einzelnen - Die in der Anfrage übergebene FieldMask gibt die Liste der Felder an.
wird im
Place
-Objekt zurückgegeben.
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, indem Sie ein Antwortfeldmaske. Übergeben Sie die Antwortfeldmaske mithilfe des URL-Parameters an die Methode.
$fields
oderfields
oder mithilfe des HTTP-HeadersX-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 ist sinnvoll, um unnötige Daten zu verarbeiten, um unnötige Verarbeitungszeiten zu vermeiden Abrechnungsgebühren.
Geben Sie eine durch Kommas getrennte Liste der Ortsdatentypen an, die zurückgegeben werden sollen. Beispiel: um den Anzeigenamen und die Adresse des Orts abzurufen.
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.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
* Das Feldplaces.name
enthält den Ressourcennamen des Orts im Format: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
,places.servesBreakfast
,places.servesBrunch
,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. Du musst 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
Hiermit können Sie eine Liste von Typen aus Typen angeben Tabelle A zum Filtern in den Suchergebnissen. In jeder Typeinschränkungskategorie können bis zu 50 Typen angegeben werden.
Ein Ort kann nur einen einzigen primären Typ aus folgenden Typen haben: Tabelle A verknüpft mit . Der primäre Typ könnte beispielsweise
"mexican_restaurant"
oder"steak_house"
. Verwenden SieincludedPrimaryTypes
undexcludedPrimaryTypes
, um die Ergebnisse zu filtern den primären Typ eines Ortes.Ein Ort kann auch mehrere Typwerte aus Typen haben Tabelle A die damit verknüpft sind. Beispiele für Restauranttypen:
"seafood_restaurant"
,"restaurant"
,"food"
"point_of_interest"
,"establishment"
.includedTypes
verwenden undexcludedTypes
, um die Ergebnisse in der Liste der Typen zu filtern, die mit einen Ort.Wenn Sie einen allgemeinen primären Typ wie
"restaurant"
oder"hotel"
enthält, kann die Antwort Orte mit einem spezifischeren primären Typ enthalten als die angegebene. Sie geben beispielsweise an, dass der primäre Typ"restaurant"
Die Antwort kann dann Orte mit dem primären Typ"restaurant"
, aber die Antwort kann auch Orte mit einer spezifischeren primären Typ wie"chinese_restaurant"
oder"seafood_restaurant"
.Wenn für eine Suche mehrere Typeinschränkungen festgelegt sind, werden nur Orte die alle Einschränkungen erfüllen, zurückgegeben. Wenn Sie beispielsweise
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, die Die zurückgegebenen Orte bieten"restaurant"
-bezogene Dienstleistungen, sind aber nicht hauptsächlich aktiv als"steak_house"
.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 aus einem suchen.
Wenn Sie sowohl das
includedTypes
( z. B."school"
) als auch dasexcludedTypes
(z. B."primary_school"
) in der Anfrage, dann der Antwort enthält Orte, die als"school"
, aber nicht als"primary_school"
. Die Antwort enthält Orte, die mit mindestens einem der folgenden Kriterien übereinstimmen:includedTypes
und keiner derexcludedTypes
.Gibt es widersprüchliche Typen, z. B. einen Typ, der in beiden
includedTypes
-Dateien vorkommt, undexcludedTypes
, wird der FehlerINVALID_REQUEST
zurückgegeben.includedPrimaryTypes
Eine durch Kommas getrennte Liste der primären Ortstypen aus Tabelle A, die eingeschlossen werden sollen bei der Suche.
excludedPrimaryTypes
Eine durch Kommas getrennte Liste der primären Ortstypen aus Tabelle A, die ausgeschlossen werden sollen über die Suche.
Gibt es widersprüchliche Primärtypen, wie ein Typ, der in beiden
includedPrimaryTypes
undexcludedPrimaryTypes
, einINVALID_ARGUMENT
Fehler wird zurückgegeben. -
languageCode
Die Sprache, in der die Ergebnisse zurückgegeben werden sollen.
- Hier finden Sie eine Liste der unterstützten Sprachen. Google oft aktualisiert die unterstützten Sprachen. 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 einINVALID_ARGUMENT
-Objekt zurück. Fehler. - Die API versucht möglichst, eine Adresse bereitzustellen, die sowohl für den Nutzer als auch Ortsansässigen. Dazu werden Adressen in der Landessprache, bei Bedarf in ein für den Nutzer lesbares Skript transliteriert, unter Berücksichtigung der Sprache. Alle übrigen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten sind die alle in derselben Sprache zurückgegeben werden, 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 ausgewählt werden. und in welcher Reihenfolge sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen. Je nach Sprache unterschiedlich, wie etwa Abkürzungen für Straßentypen oder Synonyme die in einer Sprache gültig sein können, aber nicht für eine andere.
-
maxResultCount
Gibt die maximale Anzahl der Ortsergebnisse an, die zurückgegeben werden sollen. Muss zwischen folgenden Werten liegen: 1 und 20 (Standardeinstellung) einschließlich.
-
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.
-
regionCode
Der Regionscode, der zum Formatieren der Antwort verwendet wird, angegeben als <ph type="x-smartling-placeholder"></ph> zweistelligen CLDR-Code eingeben. Es gibt keinen Standardwert.
Wenn der Ländername des Felds
formattedAddress
in der Antwort mit demregionCode
wird der Ländercode beiformattedAddress
weggelassen. Dieser Parameter hat keine Auswirkungen aufadrFormatAddress
. Dazu gehören immer das Land Name oder aufshortFormattedAddress
, wo ihn nie enthalten ist.Die meisten CLDR-Codes sind identisch mit ISO 3166-1-Codes, mit einigen nennenswerten Ausnahmen. Die ccTLD des Vereinigten Königreichs lautet beispielsweise „uk“ (.co.uk), während der ISO 3166-1-Code „gb“ lautet (technisch für die Rechtspersönlichkeit des Vereinigten Königreichs Großbritannien und Nordirland“). 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 das Display
Namen aller Restaurants in einem Umkreis von 500 m, definiert durch circle
:
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
enthält die folgenden Datenfelder: places.displayName
.
Die Antwort
hat dann folgendes 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 den Parameter
Adresse des Restaurants, Typ und Webadresse in der Antwort:
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 folgendes 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 den
Namen aller Gemischtwaren- und Spirituosengeschäfte im Umkreis von 1.000 Metern
angegeben 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:searchNearby
places.primaryType
und places.types
hinzugefügt
sodass die Antwort Typinformationen zu jedem Ort enthält, was die Auswahl des
aus den Ergebnissen auswählen.
Ortstyp aus der Suche ausschließen
Das folgende Beispiel zeigt eine „Nearby Search (New)“-Anfrage für alle Orte
vom Typ "school"
, ohne Orte vom Typ "primary_school"
, Ranking der Ergebnisse
nach Entfernung:
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 im Zentrum von San Francisco. In diesem Beispiel schließen Sie 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
Testen!
Mit dem API Explorer können Sie Beispielanfragen stellen, damit Sie sich mit der API und den API-Optionen vertraut machen können.
- Klicken Sie auf das API-Symbol
. rechts auf der Seite.
- Erweitern Sie optional Standardparameter anzeigen und legen Sie
Parameter
fields
zur Feldmaske hinzu. - 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 API Explorer auf das Symbol zum Maximieren
, um das API Explorer-Fenster zu maximieren.