Nearby Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Bei einer Nearby Search (New)-Anfrage wird als Eingabe der Suchbereich angegeben, der als Kreis definiert ist. Dieser wird durch die Breiten- und Längengradkoordinaten des Mittelpunkts des Kreises und den Radius in Metern festgelegt. Die Anfrage gibt eine Liste der übereinstimmenden Orte zurück, die jeweils durch ein Place-Objekt im angegebenen Suchgebiet dargestellt werden.

Standardmäßig enthält die Antwort Orte aller Typen im Suchgebiet. Optional können Sie die Antwort filtern, indem Sie eine Liste von Ortstypen angeben, die ausdrücklich in die Antwort ein- oder aus ihr ausgeschlossen werden sollen. Sie können beispielsweise angeben, dass nur Orte vom Typ „Restaurant“, „Bäckerei“ und „Café“ in die Antwort aufgenommen werden sollen, oder alle Orte vom Typ „Schule“ ausschließen.

Hinweis :Die Funktion „Nearby Search (New)“ ist im Places SDK for Android ab Version 3.5.0 verfügbar. Weitere Informationen finden Sie unter SDK-Version auswählen. Weitere Informationen zur Verwendung der in Version 4.0.0 hinzugefügten Kotlin APIs finden Sie in der Referenzübersicht.

Nearby Search (New)-Anfragen

Rufen Sie PlacesClient.searchNearby auf und übergeben Sie ein SearchNearbyRequest-Objekt, das die Anfrageparameter definiert, um eine Nearby Search (New)-Anfrage zu stellen.

Das SearchNearbyRequest-Objekt gibt alle erforderlichen und optionalen Parameter für die Anfrage an. Zu den erforderlichen Parametern gehören:

• Die Liste der Felder, die im Place-Objekt zurückgegeben werden sollen. Diese Liste wird auch als Feldmaske bezeichnet. Wenn Sie in der Feldliste nicht mindestens ein Feld angeben oder die Feldliste weglassen, gibt der Aufruf einen Fehler zurück.
• Die Standortbeschränkung für den Suchbereich, definiert als Breiten-/Längengrad-Paar und Radiuswert in Metern.

In dieser Beispielanfrage für die Suche in der Nähe wird angegeben, dass die Place-Objekte in der Antwort die Ortsfelder Place.Field.ID und Place.Field.DISPLAY_NAME für jedes Place-Objekt in den Suchergebnissen enthalten sollen. Außerdem werden in der Antwort nur Orte vom Typ „restaurant“ und „cafe“ zurückgegeben, aber Orte vom Typ „pizza_restaurant“ und „american_restaurant“ ausgeschlossen.

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Hinweis:Weitere Informationen zum Initialisieren von PlacesClient finden Sie unter Places API-Client initialisieren.

Mit einem CancellationToken können Sie versuchen, eine Anfrage an eine der Anfrageklassen (z. B. FetchPlaceRequest) abzubrechen. Die Stornierung erfolgt auf Best-Effort-Basis. Nach dem Einreichen einer Kündigungsanfrage erhalten Sie keine Antwort mehr. Das Ausstellen eines Kündigungstokens ist KEIN Garant dafür, dass eine bestimmte Anfrage storniert wird. Es kann sein, dass Ihnen die Anfrage trotzdem in Rechnung gestellt wird, auch wenn keine Antwort zurückgegeben wird.

Antworten von Nearby Search (New)

Die Klasse SearchNearbyResponse stellt die Antwort auf eine Suchanfrage dar. Ein SearchNearbyResponse-Objekt enthält:

• Eine Liste von Place-Objekten, die alle übereinstimmenden Orte darstellen, mit einem Place-Objekt pro übereinstimmendem Ort.
• Jedes Place-Objekt enthält nur die Felder, die durch die in der Anfrage übergebene Feldliste definiert sind.

Angenommen, Sie haben in der Anfrage eine Feldliste so definiert:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

Mit dieser Feldliste enthält jedes Place-Objekt in der Antwort nur die Orts-ID und den Namen des jeweiligen übereinstimmenden Orts. Anschließend können Sie mit den Methoden Place.getId() und Place.getName() auf diese Felder in jedem Place-Objekt zugreifen.

Weitere Beispiele für den Zugriff auf Daten in einem Place-Objekt finden Sie unter Auf Datenfelder von Ortsobjekten zugreifen.

Erforderliche Parameter

Verwenden Sie das Objekt SearchNearbyRequest, um die erforderlichen Parameter für die Suche anzugeben.

• Feldliste

  Wenn Sie Details zu einem Ort anfordern, müssen Sie die zurückzugebenden Daten im Place-Objekt für den Ort als Feldmaske angeben. Um die Feldmaske zu definieren, übergeben Sie dem SearchNearbyRequest-Objekt ein Array mit Werten aus Place.Field. 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 mindestens eines der folgenden Felder an:

  • Die folgenden Felder lösen die SKU Nearby Search (Basic) aus:

    Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.PRIMARY_TYPE, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, Place.Field.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

  • Die folgenden Felder lösen die SKU Nearby Search (Advanced) aus:

    Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS Place.Field.INTERNATIONAL_PHONE_NUMBER, Place.Field.NATIONAL_PHONE_NUMBER Place.Field.OPENING_HOURS, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.USER_RATING_COUNT Place.Field.WEBSITE_URI
    
    Hinweis:Die Felder Place.Field.PHONE_NUMBER und Place.Field.USER_RATINGS_TOTAL wurden in Version 4.0 des Places SDK for Android eingestellt. Verwenden Sie stattdessen Place.Field.INTERNATIONAL_PHONE_NUMBER und Place.USER_RATING_COUNT.

  • Die folgenden Felder lösen die SKU Nearby Search (Preferred) aus:

    Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT
  Hinweis:In Version 4.0 des Places SDK for Android wurden mehrere Felder für Ortsdaten eingestellt und neue hinzugefügt. Weitere Informationen finden Sie unter Zu den neuen Ortsdatenfeldern im Places SDK for Android 4.0 migrieren .

  Wenn Sie den Parameter für die Feldliste festlegen möchten, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setPlaceFields() auf.

  Im folgenden Beispiel wird eine Liste mit zwei Feldwerten definiert, um anzugeben, dass das Place-Objekt, das von einer Anfrage zurückgegeben wird, die Felder Place.Field.ID und Place.Field.DISPLAY_NAME enthält:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

• Standortbeschränkung

  Ein LocationRestriction-Objekt, das den zu durchsuchenden Bereich als Kreis definiert, der durch den Mittelpunkt und den Radius in Metern festgelegt wird. Der Radius muss größer als 0,0 und kleiner oder gleich 50.000,0 sein.Wenn Sie einen zu kleinen Radius angeben, wird ZERO_RESULTS als Antwort zurückgegeben.

  Wenn Sie den Parameter für die Standorteinschränkung festlegen möchten, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setLocationRestriction() auf.

Optionale Parameter

Verwenden Sie das Objekt SearchNearbyRequest, um die optionalen Parameter für die Suche anzugeben.

• Typen und Haupttypen

  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.

  Hinweis : Die Werte in Tabelle B werden nur in der Antwort zurückgegeben. Werte in Tabelle B können nicht als Filter verwendet 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 = Arrays.asList("restaurant") und excludedPrimaryTypes = Arrays.asList("steak_house") angeben, bieten die zurückgegebenen Orte "restaurant"-bezogene Dienstleistungen an, sind aber nicht in erster Linie als "steak_house" tätig.

  Wenn Sie includedTypes, excludedTypes, includedPrimaryTypes und excludedPrimaryTypes aus der Anfrage auslassen, werden bei der Suche Orte aller Typen innerhalb der Grenzen der Standorteinschränkungen zurückgegeben.

  Ein Beispiel für die Verwendung von includedTypes und excludedTypes finden Sie unter Nearby Search (New)-Anfragen.

  Eingeschlossene Typen

  Eine Liste der Ortstypen aus Tabelle A, nach denen gesucht werden soll. Wenn dieser Parameter weggelassen wird, werden Orte aller Typen zurückgegeben.

  Wenn Sie den Parameter „included_types“ festlegen möchten, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setIncludedTypes() auf.

  Ausgeschlossene Typen

  Eine Liste der 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.

  Wenn Sie den Parameter „ausgeschlossene Typen“ festlegen möchten, rufen Sie die Methode setExcludedTypes() auf, wenn Sie das SearchNearbyRequest-Objekt erstellen.

  Eingeschlossene Haupttypen

  Eine Liste der primären Ortstypen aus Tabelle A, die in eine Suche einbezogen werden sollen.

  Wenn Sie den Parameter „included primary types“ festlegen möchten, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setIncludedPrimaryTypes() auf.

  Ausgeschlossene Haupttypen

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

  Wenn Sie den Parameter „ausgeschlossene primäre Typen“ festlegen möchten, rufen Sie die Methode setExcludedPrimaryTypes() auf, wenn Sie das SearchNearbyRequest-Objekt erstellen.

• Maximale Anzahl der Ergebnisse

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

  Wenn Sie den Parameter „Maximale Anzahl von Ergebnissen“ festlegen möchten, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setMaxResultCount() auf.

• Rangpräferenz

  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.

  Wenn Sie den Parameter für die Rangpräferenz festlegen möchten, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setRankPreference() auf.

• Regionscode

  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 FORMATTED_ADDRESS in der Antwort mit regionCode übereinstimmt, wird der Ländercode aus FORMATTED_ADDRESS weggelassen.

  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.

  Wenn Sie den Parameter „Regioncode“ festlegen möchten, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setRegionCode() auf.

Zuordnungen in der App anzeigen

Wenn in Ihrer App Informationen angezeigt werden, die über PlacesClient abgerufen wurden, z. B. Fotos und Rezensionen, müssen auch die erforderlichen Quellenangaben eingeblendet werden.

Weitere Informationen finden Sie unter Richtlinien für das Places SDK für Android.