Nearby Search (New)

Bei einer „Nearby Search (New)“-Anfrage wird die zu durchsuchende Region als Kreis angegeben. Dieser wird durch die Breiten- und Längengradkoordinaten des Mittelpunkts und den Radius in Metern definiert. Die Anfrage gibt eine Liste übereinstimmender Orte zurück, die jeweils durch ein Place Objekt dargestellt werden.

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

„Nearby Search (New)“-Anfragen

Stellen Sie eine „Nearby Search (New)“-Anfrage, indem Sie PlacesClient.searchNearbyaufrufen und ein SearchNearbyRequest -Objekt übergeben, das die Anfrageparameter definiert.

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 die Ortsfelder Place.Field.ID und Place.Field.DISPLAY_NAME für jedes Place-Objekt in den Suchergebnissen enthalten sollen. Außerdem wird die Antwort so gefiltert, dass nur Orte vom Typ „Restaurant“ und „Café“ zurückgegeben werden, Orte vom Typ „Pizzeria“ und „Amerikanisches Restaurant“ jedoch ausgeschlossen werden.

// 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();
    });

„Nearby Search (New)“-Antworten

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

• Eine Liste von Place-Objekten, die alle übereinstimmenden Orte darstellen. Für jeden übereinstimmenden Ort gibt es ein Place-Objekt.
• Jedes Place Objekt enthält nur die Felder, die in der in der Anfrage übergebenen Feldliste definiert sind.

In der Anfrage haben Sie beispielsweise eine Feldliste wie folgt 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);

Diese Feldliste bedeutet, dass jedes Place-Objekt in der Antwort nur die Orts-ID und den Namen jedes übereinstimmenden Orts enthält. Mit den Methoden Place.getId() und Place.getName() können Sie dann 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 „Place“-Objekten zugreifen.

Erforderliche Parameter

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

• Feldliste

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

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

    Place.Field.ADDRESS_COMPONENTS
Place.Field.BUSINESS_STATUS
Place.Field.ADDRESS
Place.Field.DISPLAY_NAME >*
        * Verwenden Sie anstelle von Place.Field.NAME, das eingestellt wurde.
    Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL*
        * Verwenden Sie anstelle von Place.Field.ICON_URL, das eingestellt wurde.
    Place.Field.ID
Place.Field.LAT_LNG
Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.RESOURCE_NAME
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT
Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

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

    Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER*
        * Verwenden Sie anstelle von Place.Field.PHONE_NUMBER, das eingestellt wurde.
    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*
        * Verwenden Sie anstelle von Place.Field.USER_RATINGS_TOTAL, das eingestellt wurde.
    Place.Field.WEBSITE_URI

  • Die folgenden Felder lösen die Nearby Search Enterprise Plus SKU 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

  Um den Parameter für die Feldliste festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest Objekts die setPlaceFields() Methode 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 Place.Field.ID und Place.Field.DISPLAY_NAME Felder 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 die zu durchsuchende Region als Kreis definiert. Dieser wird durch den Mittelpunkt und den Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 liegen.Wenn Sie einen zu kleinen Radius angeben, wird ZERO_RESULTS als Antwort zurückgegeben.

  Um den Parameter für die Standortbeschränkung festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest Objekts die setLocationRestriction() Methode auf.

Optionale Parameter

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

• Typen und primäre Typen

  Hier können Sie eine Liste von Typen aus Typen 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 Typen Tabelle A haben, der damit verbunden ist. 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 Typwerte aus Typen 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 mit einem Ort verknüpft 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 ein primärer Typ von "restaurant" eingeschlossen werden soll. Die Antwort kann dann Orte mit dem primären Typ "restaurant" enthalten, aber die Antwort kann auch Orte mit einem spezifischeren primären Typ enthalten, wie z. B. "chinese_restaurant" oder "seafood_restaurant".

  Wenn eine Suche mit mehreren Typbeschränkungen angegeben wird, werden nur Orte die alle Beschränkungen erfüllen, zurückgegeben. 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 ein "steak_house".

  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.

  Um den Parameter für die eingeschlossenen Typen festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest Objekts die setIncludedTypes() Methode auf.

  Ausgeschlossene Typen

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

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

  Wenn es widersprüchliche Typen gibt, z. B. ein Typ, der sowohl in includedTypes als auch in excludedTypes vorkommt, wird ein INVALID_REQUEST Fehler zurückgegeben.

  Um den Parameter für die ausgeschlossenen Typen festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest Objekts die setExcludedTypes() Methode auf.

  Eingeschlossene primäre Typen

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

  Um den Parameter für die eingeschlossenen primären Typen festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest Objekts die setIncludedPrimaryTypes() Methode auf.

  Ausgeschlossene primäre Typen

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

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

  Um den Parameter für die ausgeschlossenen primären Typen festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest Objekts die setExcludedPrimaryTypes() Methode auf.

• Maximale Anzahl der Ergebnisse

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

  Um den Parameter für die maximale Anzahl der Ergebnisse festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest Objekts die setMaxResultCount() Methode auf.

• Rangpräferenz

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

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

  Um den Parameter für die Rangpräferenz festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die setRankPreference()-Methode 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 dem regionCode übereinstimmt, wird der Ländercode aus FORMATTED_ADDRESS weggelassen.

  Die meisten CLDR-Codes sind mit den ISO 3166-1-Codes identisch. Es gibt jedoch einige Ausnahmen. So lautet beispielsweise die ccTLD des Vereinigten Königreichs ist „uk“ (.co.uk) und der ISO 3166-1-Code „gb“ (technisch für die Einheit „Vereinigtes Königreich Großbritannien und Nordirland“). Der Parameter kann sich je nach anwendbarem Recht auf die Ergebnisse auswirken.

  Um den Parameter für den Regionscode festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest Objekts die setRegionCode() Methode auf.

Zuordnungen in der App anzeigen

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

Weitere Informationen finden Sie in den Richtlinien für das Places SDK for Android.