Nearby Search (New)

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. 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 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 oder fields oder mit dem HTTP-Header X-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 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.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.parkingOptionsplaces.reviewsplaces.servesBeerplaces.servesBreakfastplaces.servesBrunchplaces.servesCocktailsplaces.servesCoffeeplaces.servesDessertsplaces.servesDinnerplaces.servesLunchplaces.servesVegetarianFoodplaces.servesWineplaces.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 Sie includedPrimaryTypes und excludedPrimaryTypes, 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". Mit includedTypes und excludedTypes 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 den excludedTypes (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 der includedTypes und keinem der excludedTypes übereinstimmen.

    Wenn Typen in Konflikt stehen, 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 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 in excludedPrimaryTypes, wird ein INVALID_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 auf en gesetzt. 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 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 mit regionCode übereinstimmt, wird der Ländercode bei formattedAddress weggelassen. 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 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:searchNearby
In 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.

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.

  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 für den Parameter fields die Feldmaske fest.
  3. Bearbeiten Sie optional den Anfragetext.
  4. 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.

  5. Wählen Sie im API Explorer-Bereich das Symbol zum Maximieren Maximieren Sie den API Explorer. aus, um das Fenster „API Explorer“ zu maximieren.