Nearby Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst
Entwickler im Europäischen Wirtschaftsraum (EWR)

Einführung

Bei einer Anfrage vom Typ Nearby Search (New) wird für einen oder mehrere Ortstypen eine Liste mit passenden Orten im angegebenen Bereich zurückgegeben. Eine Feldmaske mit einem oder mehreren Datentypen ist erforderlich. Nearby Search (New) unterstützt nur POST-Anfragen.

Mit dem APIs Explorer können Sie Liveanfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen:

In der interaktiven Demo können Sie sich die Ergebnisse der neuen Suche in der Nähe auf einer Karte ansehen.

„Nearby Search (New)“-Anfragen

Eine Nearby Search (New)-Anfrage ist eine HTTP POST-Anfrage an eine URL in folgendem 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

„Nearby Search (New)“-Antworten

Die neue Nearby Search gibt ein JSON-Objekt als Antwort zurück. In der Antwort:

  • Das places-Array enthält alle übereinstimmenden Orte.
  • Jeder Ort im Array wird durch ein Place-Objekt dargestellt. Das Place-Objekt enthält detaillierte Informationen zu einem einzelnen Ort.
  • Die in der Anfrage übergebene FieldMask gibt die Liste der Felder an, die im Place-Objekt 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 Maske für das Antwortfeld an die Methode, indem Sie den URL-Parameter $fields oder fields oder den HTTP-Header X-Goog-FieldMask verwenden. Es gibt keine Standardliste der zurückgegebenen Felder in der Antwort. 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 zurückzugebenden Ortsdatentypen an. So können Sie beispielsweise 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 Nearby Search Pro-SKU aus:

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      places.adrFormatAddress
      places.attributions
      places.businessStatus
      places.containingPlaces
      places.displayName
      places.formattedAddress
      places.googleMapsLinks
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.id
      places.location
      places.name**
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

      * Adressdeskriptoren sind in der Regel für Kunden in Indien verfügbar und werden ansonsten nur zu Testzwecken angeboten.

      ** Das Feld places.name enthält den Ressourcennamen des Orts in folgendem Format: places/PLACE_ID. Verwenden Sie places.displayName, um auf den Textnamen des Orts zuzugreifen.

    • Die folgenden Felder lösen die Nearby Search Enterprise-SKU aus:

      places.currentOpeningHours
      places.currentSecondaryOpeningHours
      places.internationalPhoneNumber
      places.nationalPhoneNumber
      places.priceLevel
      places.priceRange
      places.rating
      places.regularOpeningHours
      places.regularSecondaryOpeningHours
      places.userRatingCount
      places.websiteUri

    • Die folgenden Felder lösen die Nearby Search Enterprise + Atmosphere-SKU aus:

      places.allowsDogs
      places.curbsidePickup
      places.delivery
      places.dineIn
      places.editorialSummary
      places.evChargeAmenitySummary
      places.evChargeOptions
      places.fuelOptions
      places.generativeSummary
      places.goodForChildren
      places.goodForGroups
      places.goodForWatchingSports
      places.liveMusic
      places.menuForChildren
      places.neighborhoodSummary
      places.parkingOptions
      places.paymentOptions
      places.outdoorSeating
      places.reservable
      places.restroom
      places.reviews
      places.reviewSummary
      routingSummaries*
      places.servesBeer
      places.servesBreakfast
      places.servesBrunch
      places.servesCocktails
      places.servesCoffee
      places.servesDessert
      places.servesDinner
      places.servesLunch
      places.servesVegetarianFood
      places.servesWine
      places.takeout

      * Nur Text Search und Nearby Search

  • locationRestriction

    Die zu durchsuchende Region, angegeben als Kreis, der durch Mittelpunkt und Radius in Metern definiert wird. Der Radius muss zwischen 0,0 und 50.000,0 liegen (jeweils einschließlich). Der Standardradius ist 0,0. Sie müssen in Ihrer Anfrage 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

    Hiermit können Sie eine Liste von Typen aus Tabelle A angeben, die zum Filtern der Suchergebnisse verwendet werden. In jeder Kategorie für Typbeschränkungen können bis zu 50 Typen angegeben werden.

    Ein Ort kann nur einen primären Typ aus den Typen in Tabelle A haben. 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 Orts zu filtern.

    Ein Ort kann auch mehrere Typwerte aus Typen in Tabelle A haben. Ein Restaurant kann beispielsweise die folgenden Typen haben: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Mit includedTypes und excludedTypes können Sie die Ergebnisse nach der Liste der Typen filtern, die einem Ort zugeordnet sind.

    Wenn Sie einen allgemeinen primären Typ wie "restaurant" oder "hotel" angeben, kann die Antwort Orte mit einem spezifischeren primären Typ als dem angegebenen enthalten. Sie geben beispielsweise an, dass der primäre Typ "restaurant" eingeschlossen werden soll. Die Antwort kann dann Orte mit dem primären Typ "restaurant" enthalten, aber auch Orte mit einem spezifischeren primären Typ wie "chinese_restaurant" oder "seafood_restaurant".

    Wenn für eine Suche mehrere Typeinschränkungen angegeben sind, 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, sind aber nicht in erster Linie als "steak_house" tätig.

    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 aus einer Suche ausgeschlossen werden sollen.

    Wenn Sie sowohl includedTypes ( z. B. "school") als auch excludedTypes (z. B. "primary_school") in der Anfrage angeben, enthält die Antwort Orte, die als "school", aber nicht als "primary_school" kategorisiert sind. Die Antwort enthält Orte, die mindestens einer der includedTypes entsprechen und keiner der excludedTypes.

    Wenn es Konflikte zwischen Typen gibt, z. B. wenn ein Typ sowohl in includedTypes als auch in excludedTypes vorkommt, 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 aus einer Suche ausgeschlossen werden sollen.

    Wenn es primäre Typen gibt, die in Konflikt stehen, z. B. ein Typ, der sowohl in includedPrimaryTypes als auch in excludedPrimaryTypes vorkommt, wird ein INVALID_ARGUMENT-Fehler zurückgegeben.

  • languageCode

    Die Sprache, in der die Ergebnisse zurückgegeben werden sollen.

    • Liste der unterstützten Sprachen Die unterstützten Sprachen werden regelmäßig von Google aktualisiert. Diese Liste ist daher möglicherweise nicht vollständig.
    • Wenn languageCode nicht angegeben ist, verwendet die API standardmäßig en. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API den Fehler INVALID_ARGUMENT zurück.
    • Die API versucht, eine Straßenadresse bereitzustellen, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Um dieses Ziel zu erreichen, werden Straßenadressen in der lokalen Sprache zurückgegeben, die bei Bedarf in ein für den Nutzer lesbares Schriftsystem transliteriert werden. 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 anhand 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 in einer Sprache gültig sind, in einer anderen jedoch nicht.

  • maxResultCount

    Gibt die maximale Anzahl der zurückzugebenden Ortsangabe-Ergebnisse an. Muss zwischen 1 und 20 (Standard) liegen.

  • rankPreference

    Der zu verwendende Rankingtyp. Wenn dieser Parameter weggelassen wird, werden die Ergebnisse nach Beliebtheit sortiert. Mögliche Werte:

    • POPULARITY (Standard): Die Ergebnisse werden nach ihrer Beliebtheit sortiert.
    • DISTANCE: Sortiert die Ergebnisse in aufsteigender Reihenfolge nach ihrer Entfernung vom angegebenen Ort.

  • 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 aus formattedAddress entfernt. Dieser Parameter hat keine Auswirkungen auf adrFormatAddress, das immer den Ländernamen enthält, oder auf shortFormattedAddress, 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 ist beispielsweise „uk“ (.co.uk), der ISO 3166-1-Code dagegen „gb“ (technisch für das Land „Vereinigtes Königreich von Großbritannien und Nordirland“). Der Parameter kann sich je nach anwendbarem Recht auf die Ergebnisse auswirken.

Beispiele für „Nearby Search (New)“

Orte eines bestimmten Typs finden

Im folgenden Beispiel wird eine „Nearby Search (New)“-Anfrage für die Anzeigenamen aller Restaurants im Umkreis von 500 Metern gezeigt, 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. Wenn Sie beispielsweise places.formattedAddress,places.types,places.websiteUri hinzufügen, werden die Restaurantadresse, der Typ und die Webadresse in die Antwort aufgenommen:

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 verschiedener Kategorien finden

Das folgende Beispiel zeigt eine „Nearby Search (New)“-Anfrage für die Anzeigenamen aller Convenience Stores und Spirituosengeschäfte im Umkreis von 1.000 Metern um die angegebene 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 places.primaryType und places.types der Feldmaske hinzugefügt, damit die Antwort Typinformationen zu jedem Ort enthält. So lässt sich der passende Ort leichter aus den Ergebnissen auswählen.

Das folgende Beispiel zeigt eine Nearby Search (New)-Anfrage für alle Orte des Typs "school", wobei alle Orte des Typs "primary_school" ausgeschlossen werden und 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

Alle Orte in der Nähe einer Region nach Entfernung sortiert suchen

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

Adressdeskriptoren abrufen

Adressdeskriptoren enthalten relationale Informationen zum Standort eines Orts, einschließlich Orientierungspunkten in der Nähe und enthaltener Gebiete.

Das folgende Beispiel zeigt eine Nearby Search (New)-Anfrage für Orte in der Nähe eines Einkaufszentrums in San Jose. In diesem Beispiel fügen Sie addressDescriptors in die Feldmaske ein:

curl -X POST -d '{
  "maxResultCount": 5,
  "locationRestriction": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      },"radius": 1000
    }
  },
  "includedTypes": ["restaurant", "cafe"],
  "excludedTypes": [],
  "rankPreference":"POPULARITY"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchNearby

Die Antwort enthält den in der Anfrage angegebenen Ort, eine Liste der nahegelegenen Sehenswürdigkeiten und deren Entfernung zum Ort sowie eine Liste der Gebiete und deren Enthaltenseinsbeziehung zum Ort:

  {
    "places": [
      {
        "displayName": {
          "text": "Westfield Valley Fair",
          "languageCode": "en"
        },
        "addressDescriptor": {
          "landmarks": [
            {
              "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": 114.76984,
              "travelDistanceMeters": 114.261856
            },
            {
              "name": "places/ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "placeId": "ChIJgexMlR_Lj4ARiKCKuhNnjn0",
              "displayName": {
                "text": "Valley Fair Mall Eyexam of CA",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "health",
                "point_of_interest"
              ],
              "straightLineDistanceMeters": 131.62566,
              "travelDistanceMeters": 237.33253
            },
            {
              "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI",
              "displayName": {
                "text": "Din Tai Fung",
                "languageCode": "en"
              },
              "types": [
                "establishment",
                "food",
                "point_of_interest",
                "restaurant"
              ],
              "straightLineDistanceMeters": 110.0775,
              "travelDistanceMeters": 171.41951
            },
            {
              "name": "places/ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "placeId": "ChIJwyfPQx7Lj4AR7bYI2A2Yc54",
              "displayName": {
                "text": "Abercrombie & Fitch",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 53.620117,
              "travelDistanceMeters": 2.4578214
            },
            {
              "name": "places/ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "placeId": "ChIJpycNQx7Lj4ARjhXw3PrM_kU",
              "displayName": {
                "text": "Hollister Co.",
                "languageCode": "en"
              },
              "types": [
                "clothing_store",
                "establishment",
                "point_of_interest",
                "shoe_store",
                "store"
              ],
              "spatialRelationship": "DOWN_THE_ROAD",
              "straightLineDistanceMeters": 56.53726,
              "travelDistanceMeters": 15.418246
            }
          ],
          "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": "OUTSKIRTS"
            }
          ]
        }
      },
  /.../
  }

Testen!

Mit dem APIs Explorer können Sie Beispielanfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen.

  1. Wählen Sie rechts auf der Seite das API-Symbol api aus.

  2. Bearbeiten Sie optional die Anfrageparameter.

  3. Klicken Sie auf die Schaltfläche Ausführen. Wählen Sie im Dialogfeld das Konto aus, das Sie für die Anfrage verwenden möchten.

  4. Wählen Sie im Bereich „APIs Explorer“ das Symbol für den Vollbildmodus fullscreen aus, um das APIs Explorer-Fenster zu maximieren.