Nearby Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Entwickler im Europäischen Wirtschaftsraum (EWR)

Für eine „Nearby Search (New)“-Anfrage wird die Region, in der gesucht werden soll, als Kreis angegeben. Dieser wird durch die Breiten- und Längengradkoordinaten des Mittelpunkts des Kreises und den Radius in Metern definiert. Die Anfrage gibt eine Liste übereinstimmender Orte zurück, die jeweils durch ein Place-Objekt im angegebenen Suchbereich 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 aus der Antwort ausgeschlossen werden sollen. Sie können beispielsweise festlegen, dass in der Antwort nur Orte vom Typ „Restaurant“, „Bäckerei“ und „Café“ enthalten sein sollen, oder alle Orte vom Typ „Schule“ ausschließen.

„Nearby Search (New)“-Anfragen

Stellen Sie eine „Nearby Search (New)“-Anfrage, indem Sie PlacesClient.searchNearby aufrufen 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. Dies 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ängengradpaar und Radiuswert in Metern.

In dieser Beispielanfrage für die Suche in der Nähe wird angegeben, dass die Antwortobjekte Place die Ortsfelder Place.Field.ID und Place.Field.DISPLAY_NAME für jedes Place-Objekt in den Suchergebnissen enthalten. 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 Klasse SearchNearbyResponse 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 durch die in der Anfrage übergebene Feldliste definiert werden.

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

Diese Feldliste bedeutet, dass jedes Place-Objekt in der Antwort nur die Orts-ID und den Namen jedes übereinstimmenden Orts enthält. 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 des Place-Objekts 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 für den Ort im Place-Objekt 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 eines oder mehrere 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 diese Option anstelle von Place.Field.NAME, die eingestellt wurde.
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL*
          * Verwenden Sie diese Option 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 diese Option anstelle von Place.Field.PHONE_NUMBER, die nicht mehr unterstützt wird.
      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 stattdessen Place.Field.USER_RATINGS_TOTAL, das verworfen wurde.
      Place.Field.WEBSITE_URI

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

    Wenn Sie den Parameter „field list“ 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 von einer Anfrage zurückgegebene Place-Objekt 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 angegeben 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 Standortbeschränkung festzulegen.

Optionale Parameter

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

  • Typen und primäre Typen

    Hiermit können Sie eine Liste von Typen aus 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 den Typen in 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 Orts zu filtern.

    Ein Ort kann auch mehrere Typwerte aus Typen in 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 einem Ort zugeordnet 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 der primäre Typ "restaurant" eingeschlossen werden 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 Typeinschränkungen 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 Dienste 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.

    Enthaltene 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 „included types“ festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setIncludedTypes() auf.

    Ausgeschlossene Typen

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

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

    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.

    Rufen Sie zum Festlegen des Parameters „excludedTypes“ die Methode setExcludedTypes() beim Erstellen des SearchNearbyRequest-Objekts auf.

    Eingeschlossene primäre Typen

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

    Rufen Sie zum Festlegen des Parameters „includedPrimaryTypes“ die Methode setIncludedPrimaryTypes() beim Erstellen des SearchNearbyRequest-Objekts auf.

    Ausgeschlossene primäre Typen

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

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

    Rufen Sie zum Festlegen des Parameters „excluded primary types“ (ausgeschlossene primäre Typen) die Methode setExcludedPrimaryTypes() auf, wenn Sie das SearchNearbyRequest-Objekt erstellen.

  • Maximale Anzahl der Ergebnisse

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

    Wenn Sie den Parameter für die maximale Anzahl von Ergebnissen festlegen möchten, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setMaxResultCount() auf.

  • Rangfolge

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

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

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

  • Regionscode

    Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger CLDR-Code. 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 entfernt.

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

    Wenn Sie den Parameter für den Ländercode 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 durch Aufrufen von PlacesClient eingeholt 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 for Android.