Eine Nearby Search (New)-Anfrage übernimmt einen oder mehrere Ortstypen und gibt eine Liste übereinstimmender Orte innerhalb des angegebenen Bereichs 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, um sich mit der API und den API-Optionen vertraut zu machen:
Testen!„Nearby Search (neu)“-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 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
Antworten für „Nearby Search (New)“
„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. DasPlace
-Objekt 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, indem Sie eine Antwortfeldmaske erstellen. Übergeben Sie die Antwortfeldmaske mit dem URL-Parameter
$fields
oderfields
oder mit dem HTTP-HeaderX-Goog-FieldMask
an die Methode. Die Antwort enthält keine Standardliste der zurückgegebenen Felder. Wenn Sie die Feldmaske weglassen, gibt die Methode einen Fehler zurück.Die Maskierung von Feldern hat sich bewährt, damit keine unnötigen Daten angefordert werden. So lassen sich unnötige Verarbeitungszeiten und Gebühren vermeiden.
Geben Sie eine durch Kommas getrennte Liste von Ortsdatentypen an, die zurückgegeben werden sollen. Beispiel: Der Anzeigename und die Adresse des Orts werden abgerufen.
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.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 in folgendem 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
, {1/7/}, {2/7, {2/7/}, {2/7, {2/7/}, {2/7, {2/7/}, {2/7/}, {2/7,{2/7,{2/2/2,2/2},places.menuForChildren
,places.menuForChildren
,places.parkingOptions
,places.menuForChildren
,places.parkingOptions
places.reviews
places.servesBeer
places.servesBreakfast
places.servesBrunch
places.servesCocktails
places.servesCoffee
places.servesDesserts
places.servesDinner
places.servesLunch
places.servesVegetarianFood
places.servesWine
places.takeout
-
locationRestriction
Die zu durchsuchende Region, angegeben als Kreis, definiert durch Mittelpunkt und Radius in Metern. Der Umkreis muss zwischen 0,0 und 50000,0 (jeweils 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
-
„includedTypes“/„excludedTypes“, „includedPrimaryTypes/excludedPrimaryTypes“
Zur Angabe einer Liste mit Typen aus dem Typ Tabelle A, der zum Filtern der Suchergebnisse verwendet wird In jeder Typeinschränkungskategorie können bis zu 50 Typen angegeben werden.
Ein Ort kann nur einen einzigen primären Typ aus dem zugehörigen Typ Tabelle A haben. 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 den Typen Tabelle A haben. Ein Restaurant könnte beispielsweise die folgenden Typen haben:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. MitincludedTypes
undexcludedTypes
können Sie die Ergebnisse in der Liste der mit einem Ort verknüpften Typen filtern.Wenn bei einer Suche mehrere Typeinschränkungen angegeben werden, werden nur Orte zurückgegeben, die alle Einschränkungen erfüllen. Wenn Sie beispielsweise
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
angeben, bieten die zurückgegebenen Orte"restaurant"
-bezogene Dienste an, werden aber nicht hauptsächlich als"steak_house"
verwendet.includedTypes
Eine durch Kommas getrennte Liste der Ortstypen aus Tabelle A, nach denen gesucht werden soll. Wenn dieser Parameter weggelassen wird, werden Orte aller Typen zurückgegeben.
excludedTypes
Eine durch Kommas getrennte Liste von Ortstypen aus Tabelle A, die bei einer Suche ausgeschlossen werden sollen.
Wenn du in der Anfrage sowohl den
includedTypes
( z. B."school"
) als auch denexcludedTypes
(z. B."primary_school"
) angibst, enthält die Antwort Orte, die als"school"
kategorisiert sind, aber nicht als"primary_school"
. Die Antwort enthält Orte, die mit mindestens einem derincludedTypes
und keinem derexcludedTypes
übereinstimmen.Wenn Typen in Konflikt stehen, z. B. wenn ein Typ sowohl in
includedTypes
als auch inexcludedTypes
vorkommt, wird einINVALID_REQUEST
-Fehler zurückgegeben.includedPrimaryTypes
Eine durch Kommas getrennte Liste der primären Ortstypen aus Tabelle A, die in eine Suche einbezogen werden sollen.
excludedPrimaryTypes
Eine durch Kommas getrennte Liste der primären Ortstypen aus Tabelle A, die bei einer Suche ausgeschlossen werden sollen.
Wenn in Konflikt stehende Primärtypen vorhanden sind, z. B. ein Typ sowohl in
includedPrimaryTypes
als auch inexcludedPrimaryTypes
, wird einINVALID_ARGUMENT
-Fehler zurückgegeben. -
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 von Google häufig aktualisiert. Daher ist diese Liste unter Umständen nicht vollständig.
- Wenn
languageCode
nicht angegeben ist, wird die API standardmäßig aufen
gesetzt. 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 den Nutzer als auch für Einheimische lesbar ist. Dazu werden Adressen in der lokalen Sprache zurückgegeben und bei Bedarf in ein für den Nutzer lesbares Skript transkribiert. Dabei wird die bevorzugte Sprache berücksichtigt. Alle übrigen Adressen werden in der bevorzugten Sprache zurückgegeben. Alle Adresskomponenten werden in derselben Sprache zurückgegeben, die in 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, sowie 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 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 (Standardwert) liegen.
-
rankPreference
Die zu verwendende Rangfolgenart. Wenn dieser Parameter weggelassen wird, werden die Ergebnisse nach Beliebtheit sortiert. Folgende Werte sind möglich:
POPULARITY
(Standard): Ergebnisse werden nach ihrer Beliebtheit sortiert.DISTANCE
sortiert die Ergebnisse in aufsteigender Reihenfolge nach ihrer Entfernung vom angegebenen Standort.
-
regionCode
Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger CLDR-Code-Wert. Es gibt keinen Standardwert.
Wenn der Ländername des Felds
formattedAddress
in der Antwort mitregionCode
übereinstimmt, wird der Ländercode beiformattedAddress
weggelassen. 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 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 „The United Kingdom of Great Britain and Northern Ireland“). Der Parameter kann sich gemäß anwendbarem Recht auf Ergebnisse auswirken.
Beispiele für „Nearby Search (neu)“
Orte eines bestimmten Typs finden
Das folgende Beispiel zeigt eine „Nearby Search (New)“-Anfrage für die Anzeigenamen aller Restaurants in einem 500-Meter-Radius, 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 Header X-Goog-FieldMask
gibt an, dass die Antwort die folgenden Datenfelder enthält: 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 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 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" } }, ... }
Verschiedene Arten von Orten suchen
Das folgende Beispiel zeigt eine „Nearby Search (New)“-Anfrage für die Anzeigenamen aller Minimärkte und Spirituosengeschäfte in einem Radius von 1.000 m des angegebenen circle
-Objekts:
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
places.primaryType
und places.types
der Feldmaske hinzugefügt, sodass die Antwort Typinformationen zu jedem Ort enthält. So lässt sich der entsprechende Ort aus den Ergebnissen leichter auswählen.
Ortstyp aus einer Suche ausschließen
Das folgende Beispiel zeigt eine „Nearby Search (New)“-Anfrage für alle Orte des Typs "school"
, mit Ausnahme aller Orte des Typs "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, Ranking nach Entfernung
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.
- Maximieren Sie optional Standardparameter anzeigen und legen Sie für den Parameter
fields
die Feldmaske fest. - Bearbeiten Sie optional den Anfragetext.
- Klicken Sie auf die Schaltfläche Execute (Ausführen). Wählen Sie im Pop-up-Fenster das Konto aus, mit dem Sie die Anfrage stellen möchten.
Wählen Sie im API Explorer-Bereich das Symbol zum Maximieren aus, um das Fenster „API Explorer“ zu maximieren.