Nearby Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Bei einer Nearby Search (New)-Anfrage wird ein oder mehrere Ortstypen angegeben und eine Liste der passenden Orte im angegebenen Gebiet zurückgegeben. Eine Feldmaske mit mindestens einem Datentyp ist erforderlich. Die Nearby Search (neu) unterstützt nur POST-Anfragen.

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

Testen!

In der interaktiven Demo sehen Sie, wie die Ergebnisse der Nearby Search (Neu) auf einer Karte angezeigt werden.

Nearby Search (New)-Anfragen

Eine Nearby Search (New)-Anfrage ist eine HTTP POST-Anfrage an eine URL in folgender Form:

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 von Nearby Search (New)

Die Nearby Search (Neu) 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 Antwortfeldmaske 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 Feldmaskierung 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 Ortsdatentypen an, die zurückgegeben werden sollen. Beispielsweise können Sie so 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 mindestens eines 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.containingPlaces, places.displayName, places.formattedAddress, places.googleMapsLinks*, places.googleMapsUri, places.iconBackgroundColor, places.iconMaskBaseUri, places.id, places.location, places.name**, places.photos, places.plusCode, places.primaryType, places.primaryTypeDisplayName, places.pureServiceAreaBusiness, places.shortFormattedAddress, places.subDestinations, places.types, places.utcOffsetMinutes, places.viewport

      * Das Feld places.googleMapsLinks befindet sich in der Pre-GA-Vorabversion und die Nutzung während der Vorabversion ist kostenlos, d. h., die Abrechnung erfolgt mit 0 $.

      ** 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 SKU Nearby Search (Advanced) 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 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.routingSummaries,* places.servesBeer, places.servesBreakfast, places.servesBrunch, places.servesCocktails, places.servesCoffee, places.servesDessert, places.servesDinner, places.servesLunch, places.servesVegetarianFood, places.servesWine, places.takeout

      * Nur Textsuche und Nearby Search

  • locationRestriction

    Der zu durchsuchende Bereich wird als Kreis mit Mittelpunkt und Radius in Metern angegeben. Der Radius muss zwischen 0,0 und 50.000,0 liegen. 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

    Hier können Sie eine Liste von Typen aus den Typen in Tabelle A angeben, mit der die Suchergebnisse gefiltert werden. In jeder Kategorie für Einschränkungen können bis zu 50 Typen angegeben werden.

    Ein Ort kann nur einen einen primären Typ aus den Typen haben, die ihm in Tabelle A zugeordnet sind. Der primäre Typ kann beispielsweise "mexican_restaurant" oder "steak_house" sein. Mit includedPrimaryTypes und excludedPrimaryTypes können Sie die Ergebnisse nach dem primären Typ eines Orts filtern.

    Ein Ort kann auch mehrere Typenwerte aus den Typen haben, die ihm in Tabelle A zugeordnet sind. 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 in der Liste der Typen filtern, die mit einem Ort verknüpft sind.

    Wenn Sie einen allgemeinen primären Typ angeben, z. B. "restaurant" oder "hotel", kann die Antwort Orte mit einem spezifischeren primären Typ als dem angegebenen enthalten. Sie geben beispielsweise an, dass ein primärer Typ von "restaurant" enthalten sein 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 Einschränkungen des Typs 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 Dienstleistungen 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 von einer Suche ausgeschlossen werden sollen.

    Wenn Sie in der Anfrage sowohl den includedTypes ( z. B. "school") als auch den 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 mindestens einem der includedTypes entsprechen und keinem 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 Hauptorttypen aus Tabelle A, die in die Suche einbezogen werden sollen.

    excludedPrimaryTypes

    Eine kommagetrennte Liste der primären Ortstypen aus Tabelle A, die von einer Suche ausgeschlossen werden sollen.

    Wenn es Konflikte bei primären Typen gibt, z. B. wenn ein Typ sowohl in includedPrimaryTypes als auch in excludedPrimaryTypes vorkommt, wird ein INVALID_ARGUMENT-Fehler zurückgegeben.

  • languageCode

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

    • Hier finden Sie eine 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 Adresse anzugeben, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Dazu werden Straßenadressen in der jeweiligen Landessprache zurückgegeben, die bei Bedarf in ein für den Nutzer lesbares Schriftbild transkribiert werden, wobei die bevorzugte Sprache berücksichtigt wird. Alle übrigen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle 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 sein können, in einer anderen aber nicht.

  • maxResultCount

    Gibt die maximale Anzahl der zu retournierenden Ortsergebnisse an. Muss zwischen 1 und 20 (Standard) liegen.

  • rankPreference

    Der zu verwendende Ranking-Typ. Wenn dieser Parameter weggelassen wird, werden die Ergebnisse nach Beliebtheit sortiert. Kann einer der folgenden Werte sein:

    • POPULARITY (Standardeinstellung): Die Ergebnisse werden nach Beliebtheit sortiert.
    • DISTANCE: Die Ergebnisse werden in aufsteigender Reihenfolge nach ihrer Entfernung vom angegebenen Standort sortiert.

  • regionCode

    Der Regionscode, der zum Formatieren der Antwort verwendet wird. Er wird als zweistelliger CLDR-Code angegeben. Es gibt keinen Standardwert.

    Wenn der Ländername des Felds formattedAddress in der Antwort mit regionCode übereinstimmt, wird der Ländercode aus formattedAddress weggelassen. Dieser Parameter hat keine Auswirkungen auf adrFormatAddress, in dem der Ländername immer enthalten ist, und auf shortFormattedAddress, in dem er nie enthalten ist.

    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), der ISO 3166-1-Code dagegen „gb“ (technisch für die Entität „Vereinigtes Königreich von Großbritannien und Nordirland“). Der Parameter kann sich auf die Ergebnisse auswirken, die gemäß anwendbarem Recht angezeigt werden.

Beispiele für Nearby Search (New)

Orte eines bestimmten Typs finden

Im folgenden Beispiel wird eine Nearby Search (New)-Anfrage für die Anzeige der Namen aller Restaurants im Umkreis von 500 Metern um circle gezeigt: 

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 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"
      }
    },
...
}

Orte verschiedener Typen finden

Im folgenden Beispiel wird eine Nearby Search (New)-Anfrage für die Anzeigenamen aller Supermärkte und Spirituosenläden in einem Umkreis von 1.000 Metern um die angegebene circle gezeigt:

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, damit die Antwort Informationen zum Typ jedes Orts enthält. So lässt sich der richtige Ort in den Ergebnissen leichter auswählen.

Im folgenden Beispiel wird eine Nearby Search (New)-Anfrage für alle Orte vom Typ "school" ohne Orte vom Typ "primary_school" gezeigt. Die Ergebnisse werden nach Entfernung sortiert:

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 einer Region suchen, sortiert nach Entfernung

Das folgende Beispiel zeigt eine Nearby Search (New)-Anfrage nach Orten in der Nähe eines Punkts in der Innenstadt von San Francisco. In diesem Beispiel wird der Parameter rankPreference verwendet, 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, um sich mit der API und den API-Optionen vertraut zu machen.

  1. Wählen Sie rechts auf der Seite das API-Symbol Maximieren Sie den API Explorer. aus.
  2. Maximieren Sie optional Standardparameter anzeigen und legen Sie den Parameter fields auf die Feldmaske fest.
  3. Optional können Sie den Anfragetext bearbeiten.
  4. Klicken Sie auf die Schaltfläche Ausführen. Wählen Sie im Pop-up-Fenster das Konto aus, mit dem Sie die Anfrage stellen möchten.

  5. Klicken Sie im API Explorer-Steuerfeld auf das Symbol zum Maximieren Maximieren Sie den API Explorer., um das Fenster des API Explorer zu maximieren.