Nearby Search (New)

Für eine „Nearby Search (New)“-Anfrage wird die Region als Kreis angegeben, die durch die Breiten- und Längengradkoordinaten des Kreismittelpunkts sowie den Radius in Metern definiert ist. Die Anfrage gibt eine Liste mit übereinstimmenden Orten im angegebenen Suchbereich zurück. Jeder Ort wird durch ein Place-Objekt dargestellt.

Standardmäßig enthält die Antwort Orte aller Typen innerhalb des Suchbereichs. Optional können Sie die Antwort filtern. Geben Sie dazu eine Liste von Ortstypen an, die explizit in die Antwort aufgenommen oder davon ausgeschlossen werden sollen. Sie können beispielsweise festlegen, dass nur Orte mit dem Typ „Restaurant“, „Bäckerei“ oder „Café“ in die Antwort aufgenommen oder alle Orte des Typs „Schule“ ausgeschlossen werden.

„Nearby Search (neu)“-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. Sie wird auch als Feldmaske bezeichnet. Wenn Sie mindestens ein Feld in der Feldliste nicht angeben oder die Feldliste auslassen, gibt der Aufruf einen Fehler zurück.
  • Die Standortbeschränkung für das Suchgebiet, definiert als Breiten-/Längengradpaar und Radiuswert, in Metern.

In diesem Beispiel für eine „Nearby Search“-Anfrage 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, aber Orte der Typen „pizza_restaurant“ und „american_restaurant“ 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.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 (New)“

Die Klasse SearchNearbyResponse stellt die Antwort auf eine 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 durch die in der Anfrage übergebene Feldliste definiert werden.

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 übereinstimmenden Orts enthält. Sie können dann die Methoden Place.getId() und Place.getName() verwenden, um auf diese Felder in jedem Place-Objekt zuzugreifen.

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 angeben, die im Place-Objekt für den Ort als Feldmaske zurückgegeben werden sollen. Übergeben Sie zum Definieren der Feldmaske ein Wertearray aus Place.Field an das Objekt SearchNearbyRequest. Die Maskierung von Feldern hat sich bewährt, damit 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

    Um den Parameter „field list“ festzulegen, rufen Sie beim Erstellen des SearchNearbyRequest-Objekts die Methode setPlaceFields() auf.

    Im folgenden Beispiel wird eine Liste mit zwei Feldwerten definiert. Damit wird angegeben, 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, definiert durch Mittelpunkt und Radius in Metern. Der Radius muss zwischen größer als 0,0 und kleiner oder gleich 50.000,0 liegen.Wenn Sie einen zu kleinen Umkreis angeben, wird als Antwort ZERO_RESULTS zurückgegeben.

    Um den Parameter für die Standortbeschränkung festzulegen, 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

    Zur Angabe einer Liste mit Typen aus dem Typ Tabelle A, der zum Filtern der Suchergebnisse verwendet wird In jeder Typeinschränkungskategorie können bis zu 50 Typen angegeben werden.

    Ein Ort kann nur einen einzigen primären Typ aus dem zugehörigen Typ 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 Ortes zu filtern.

    Ein Ort kann auch mehrere Typwerte aus den Typen Tabelle A haben. Ein Restaurant könnte 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 mit einem Ort verknüpften Typen filtern.

    Wenn bei einer Suche mehrere Typeinschränkungen angegeben werden, werden nur Orte zurückgegeben, die alle Einschränkungen erfüllen. Wenn du beispielsweise includedTypes = Arrays.asList("restaurant") und excludedPrimaryTypes = Arrays.asList("steak_house") angibst, bieten die zurückgegebenen Orte "restaurant"-bezogene Dienste an, werden aber nicht hauptsächlich 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. Wenn dieser Parameter weggelassen wird, werden Orte aller Typen zurückgegeben.

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

    Ausgeschlossene Typen

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

    Wenn du in der Anfrage sowohl den includedTypes (z. B. "school") als auch den excludedTypes (z. B. "primary_school") angibst, enthält die Antwort Orte, die als "school" kategorisiert sind, aber nicht als "primary_school". Die Antwort enthält Orte, die mit mindestens einem der includedTypes und keinem der excludedTypes übereinstimmen.

    Wenn Typen in Konflikt stehen, z. B. wenn ein Typ sowohl in includedTypes als auch in excludedTypes vorkommt, 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 einbezogen 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 bei einer Suche ausgeschlossen werden sollen.

    Wenn in Konflikt stehende Primärtypen vorhanden sind, z. B. ein Typ sowohl in includedPrimaryTypes als auch in excludedPrimaryTypes, wird ein INVALID_ARGUMENT-Fehler zurückgegeben.

    Um den Parameter für ausgeschlossene primäre Typen festzulegen, 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 (Standardwert) liegen.

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

  • Rangeinstellung

    Die zu verwendende Rangfolgenart. Wenn dieser Parameter weggelassen wird, werden die Ergebnisse nach Beliebtheit sortiert. Folgende Werte sind möglich:

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

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

  • Regionscode

    Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger CLDR-Code-Wert. Es gibt keinen Standardwert.

    Wenn der Ländername des Felds formattedAddress in der Antwort mit regionCode übereinstimmt, wird der Ländercode bei formattedAddress weggelassen.

    Die meisten CLDR-Codes sind mit den ISO 3166-1-Codes identisch. Es gibt jedoch einige Ausnahmen. Die ccTLD des Vereinigten Königreichs lautet beispielsweise „uk“ (.co.uk), während der ISO 3166-1-Code „gb“ lautet (technisch für die Rechtspersönlichkeit „The United Kingdom of Great Britain and Northern Ireland“). Der Parameter kann sich gemäß anwendbarem Recht auf Ergebnisse auswirken.

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

Zuordnungen in der App anzeigen

Wenn in Ihrer App Informationen aus PlacesClient angezeigt werden, z. B. Fotos und Rezensionen, müssen auch die erforderlichen Quellenangaben vorhanden sein.

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