Nearby Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Bei „Nearby Search (New)“-Anfragen wird die als Kreis angegebene Region als Eingabe verwendet, die durch die Breiten- und Längengradkoordinaten des Mittelpunkts des Kreises und den Radius in Metern definiert ist. Bei der Anfrage wird eine Liste mit übereinstimmenden Orten im angegebenen Suchbereich zurückgegeben, die jeweils durch ein Place-Objekt dargestellt werden.

Standardmäßig enthält die Antwort Orte aller Typen innerhalb des Suchbereichs. Sie können die Antwort optional filtern, indem Sie eine Liste von Ortstypen angeben, die explizit in die Antwort aufgenommen oder von 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.

„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 Objekt SearchNearbyRequest gibt alle erforderlichen und optionalen Parameter für die Anfrage an. Zu den erforderlichen Parametern gehören:

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

In diesem Beispiel für eine Suchanfrage in der Nähe wird angegeben, dass die Place-Antwortobjekte die Ortsfelder Place.Field.ID und Place.Field.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, aber Orte des Typs „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.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 einer Suchanfrage dar. Ein SearchNearbyResponse-Objekt enthält Folgendes:

  • 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 in der Feldliste definiert sind, die in der Anfrage übergeben wurde.

In der Anfrage haben Sie beispielsweise 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 des entsprechenden Orts enthält. Anschließend können Sie mit den Methoden Place.getId() und Place.getName() in jedem Place-Objekt auf diese Felder zugreifen.

Weitere Beispiele für den Zugriff auf Daten in einem Place-Objekt finden Sie unter Datenfelder des Place Place-Objekts aufrufen.

Erforderliche Parameter

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

  • Liste der Felder

    Wenn Sie Ortsdetails 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 ein Array von Werten von Place.Field an das SearchNearbyRequest-Objekt. Die Maskierung von Feldern hat sich bewährt, um sicherzustellen, dass keine unnötigen Daten angefordert werden. So lassen sich unnötige Verarbeitungszeiten und Gebühren vermeiden.

    Geben Sie eines oder mehrere 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.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.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

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

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

    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 von einer Anfrage zurückgegebene Place-Objekt die Felder Place.Field.ID und Place.Field.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.NAME);

  • Standortbeschränkung

    Ein LocationRestriction-Objekt, das die zu durchsuchende Region als Kreis definiert, der durch den Mittelpunkt und einen Radius in Metern definiert ist. 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 Standortbeschränkung festlegen möchten, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setLocationRestriction() auf.

Optionale Parameter

Mit dem Objekt SearchNearbyRequest können Sie die optionalen Parameter für die Suche angeben.

  • Typen und primäre Typen

    Geben Sie hier eine Liste von Typen aus Tabelle A an, die zum Filtern der Suchergebnisse verwendet werden. In jeder Typeinschränkungskategorie können bis zu 50 Typen angegeben werden.

    Einem Ort kann nur ein einziger Haupttyp aus dem Typ Tabelle A zugeordnet sein. 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 dem Typ Tabelle A haben. 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 Typen zu filtern, die mit einem Ort verknüpft sind.

    Wenn für eine Suche mehrere Typeinschränkungen gelten, 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, stellen die zurückgegebenen Orte "restaurant"-bezogene Dienste bereit, werden aber nicht primär als "steak_house" verwendet.

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

    Eingeschlossene Typen

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

    Zum Festlegen des enthaltenen Typenparameters 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 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 mit mindestens einem der includedTypes und keinem der excludedTypes übereinstimmen.

    Wenn Typen in Konflikt stehen, z. B. ein Typ, der sowohl in includedTypes als auch in excludedTypes enthalten ist, wird ein INVALID_REQUEST-Fehler zurückgegeben.

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

    Eingeschlossene primäre Typen

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

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

    Ausgeschlossene primäre Typen

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

    Wenn Primärtypen in Konflikt stehen, z. B. ein Typ, der sowohl in includedPrimaryTypes als auch in excludedPrimaryTypes enthalten ist, wird der Fehler INVALID_ARGUMENT zurückgegeben.

    Zum Festlegen des ausgeschlossenen primären Typparameters rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setExcludedPrimaryTypes() auf.

  • Maximale Anzahl von Ergebnissen

    Gibt die maximale Anzahl der Ortsergebnisse an, die zurückgegeben werden sollen. Der Wert muss zwischen 1 und 20 (Standardeinstellung) liegen.

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

  • Rangfolgeneinstellung

    Der zu verwendende Rankingtyp. Wenn Sie diesen Parameter nicht angeben, werden die Ergebnisse nach Beliebtheit sortiert. Folgende Werte sind möglich:

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

    Zum Festlegen des Parameters für die Rangeinstellung 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 formattedAddress in der Antwort mit regionCode übereinstimmt, wird der Ländercode in formattedAddress 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) und der ISO 3166-1-Code „gb“ (technisch für die Rechtspersönlichkeit „The United Kingdom of Great Britain and Northern Ireland“). Der Parameter kann sich gemäß geltendem Recht auf Ergebnisse auswirken.

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

Zuordnungen in der App anzeigen

Wenn Ihre App Informationen aus PlacesClient anzeigt, z. B. Fotos und Rezensionen, müssen auch die erforderlichen Quellenangaben angezeigt werden.

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