Nearby Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Bei einer Nearby Search (New)-Anfrage wird als Eingabe die zu durchsuchende Region angegeben, die als Kreis definiert ist. Dieser Kreis wird durch die Breiten- und Längengradkoordinaten des Mittelpunkts 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 mit 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.

Anfragen für Nearby Search (neu)

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

Im SearchNearbyRequest-Objekt werden alle erforderlichen und optionalen Parameter für die Anfrage angegeben. 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 mindestens ein Feld angeben oder die Feldliste auslassen, wird beim Aufruf ein Fehler zurückgegeben.
  • 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 nur Orte vom Typ „Restaurant“ und „Café“ zurückgegeben, aber Orte vom Typ „Pizza_restaurant“ und „American_restaurant“ werden 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();
    });

Antworten für Nearby Search (neu)

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

  • Eine Liste von Place-Objekten, die alle übereinstimmenden Orte repräsentieren, 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 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. Feldmaskierung ist eine gute Designmethode, um sicherzustellen, dass keine unnötigen Daten angefordert werden. So lassen sich unnötige Verarbeitungszeiten und Abrechnungskosten 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

    • 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

    Rufen Sie die Methode setPlaceFields() auf, um den Parameter für die Feldliste festzulegen, wenn Sie das SearchNearbyRequest-Objekt erstellen.

    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);

  • Standorteinschrä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.

    Rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setLocationRestriction() auf, um den Parameter für die Standorteinschränkung festzulegen.

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 denen die Suchergebnisse gefiltert werden sollen. 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. Verwenden Sie includedPrimaryTypes und excludedPrimaryTypes, um die Ergebnisse nach dem primären Typ eines Orts zu 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". Verwenden Sie includedTypes und excludedTypes, um die Ergebnisse in der Liste der mit einem Ort verknüpften Typen zu filtern.

    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 werden, werden nur Orte zurückgegeben, die allen Einschränkungen entsprechen. 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.

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

    Wenn Sie in der Anfrage sowohl includedTypes (z. B. "school") als auch 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 bei den Typen gibt, z. B. wenn ein Typ sowohl in includedTypes als auch in excludedTypes vorkommt, wird der Fehler INVALID_REQUEST zurückgegeben.

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

    Eingeschlossene Haupttypen

    Eine Liste der primären Ortstypen aus Tabelle A, die in die 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 zu Konflikten bei den primären Typen kommt, z. B. wenn ein Typ sowohl in includedPrimaryTypes als auch in excludedPrimaryTypes vorkommt, wird der Fehler INVALID_ARGUMENT zurückgegeben.

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

  • 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

    Die Art des Rankings, die verwendet werden soll. Wenn dieser Parameter weggelassen wird, werden die Ergebnisse nach Beliebtheit sortiert. Kann eine der folgenden Optionen sein:

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

    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 dem regionCode übereinstimmt, wird der Ländercode aus FORMATTED_ADDRESS entfernt.

    Die meisten CLDR-Codes stimmen mit ISO 3166-1-Codes überein, 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.