Diese Seite wurde von der Cloud Translation API übersetzt.

Nearby Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

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 Objekt Place 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 oder fields oder den HTTP-Header X-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
```
Hinweis : Leerzeichen sind in der Feldliste nicht zulässig.

Verwenden Sie *, um alle Felder abzurufen.
```
X-Goog-FieldMask: *
```
Mit dem Platzhalter „*“ werden alle Felder ausgewählt. Während dieser Platzhalter in der Entwicklung verwendet werden kann, rät Google von der Verwendung der Platzhalter-Antwortfeldmaske (*) in der Produktion ab, da eine große Datenmenge zurückgegeben werden kann.

Weitere Informationen zur Verwendung von places.iconMaskBaseUri und places.iconBackgroundColor finden Sie im Abschnitt Place-Symbole.

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.adrFormatAddressplaces.nameplaces.subDestinationsplaces.typesplaces.utcOffsetMinutesplaces.viewport
  
  places/PLACE_ID Verwenden Sie places.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.servesBrunchplaces.servesBreakfastplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.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.

Hinweis : Die Werte in Tabelle B werden nur in der Antwort zurückgegeben. Sie können Werte in Tabelle B nicht als Filter verwenden.

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 Sie includedPrimaryTypes und excludedPrimaryTypes, 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 Sie includedTypes und excludedTypes, 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.

Wenn Sie includedTypes, excludedTypes, includedPrimaryTypes und excludedPrimaryTypes in der Anfrage weglassen, gibt die Suche Orte für alle Typen innerhalb der Standortbeschränkungsgrenzen zurück.

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 auch excludedTypes (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 der includedTypes und keinem der excludedTypes übereinstimmen.

Wenn Typen in Konflikt stehen, z. B. ein Typ, der sowohl in includedTypes als auch in excludedTypes enthalten ist, wird ein INVALID_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 in excludedPrimaryTypes enthalten ist, wird der Fehler INVALID_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äßig en verwendet. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API den Fehler INVALID_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 mit regionCode übereinstimmt, wird der Ländercode in formattedAddress weggelassen. Dieser Parameter hat keine Auswirkungen auf adrFormatAddress, das immer den Ländernamen enthält, oder auf shortFormattedAddress, 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:searchNearby

In 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.

Nearby Search (New)

„Nearby Search (New)“-Anfragen

„Nearby Search (New)“-Antworten

Erforderliche Parameter

FieldMask

locationRestriction

Optionale Parameter

eingeschlossen

includedTypes

excludedTypes

includedPrimaryTypes

excludedPrimaryTypes

languageCode

maxResultCount

rankPreference

regionCode