Text Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Bei Verwendung von „Text Search (New)“ werden Informationen zu verschiedenen Orten auf Grundlage eines Textstrings zurückgegeben, z. B. „Pizza in München“, „Schuhgeschäfte in der Nähe von Hamburg“ oder „Hauptstraße 123“. Der Dienst gibt eine Liste mit Orten zurück, die dem Textstring und ggf. der festgelegten Standortgewichtung entsprechen.

Der Dienst ist besonders nützlich, um mehrdeutige Adressabfragen in einem automatisierten System durchzuführen. Nicht-Adresskomponenten des Strings können sowohl mit Unternehmen als auch mit Adressen übereinstimmen. Beispiele für mehrdeutige Adressabfragen sind schlecht formatierte Adressen oder Anfragen, die nicht zu Adressen gehörende Komponenten wie Unternehmensnamen enthalten. Bei Anfragen wie den ersten beiden Beispielen werden möglicherweise keine Ergebnisse zurückgegeben, es sei denn, ein Standort – z. B. eine Region, eine Standortbeschränkung oder eine Standortvorgabe – ist festgelegt.

„Text Search (New)“ ähnelt Nearby Search (New). Der Hauptunterschied zwischen den beiden ist, dass Sie bei der Textsuche (neu) einen beliebigen Suchstring angeben können, während für die Nearby Search (neu) ein bestimmter Suchbereich erforderlich ist.

„10 High Street, UK“ oder „123 Main Street, USA“	Mehrere „High Streets“ im Vereinigten Königreich; mehrere „Main Streets“ in den USA. Die Abfrage gibt nur dann die gewünschten Ergebnisse zurück, wenn eine Standortbeschränkung festgelegt ist.
„Kettenrestaurant New York“	Mehrere Standorte von „ChainRestaurant“ in New York; keine Adresse und kein Straßenname
„10 High Street, Escher, Vereinigtes Königreich“ oder „123 Main Street, Pleasanton, USA“	Es gibt nur eine „High Street“ in der britischen Stadt Escher und nur eine „Main Street“ in der US-amerikanischen Stadt Pleasanton, Kalifornien.
„UniqueRestaurantName New York“	Es gibt nur eine Einrichtung mit diesem Namen in New York. Zur Unterscheidung ist keine Adresse erforderlich.
„Pizzerie in New York“	Diese Suchanfrage enthält eine Standortbeschränkung und „Pizzeria“ ist ein klar definierter Ortstyp. Es werden mehrere Ergebnisse zurückgegeben.
„[phone]“	Diese Abfrage enthält eine Telefonnummer. Es werden mehrere Ergebnisse für Orte zurückgegeben, die mit dieser Telefonnummer verknüpft sind. Hinweis : Die besten Ergebnisse bei der Suche nach einer Telefonnummer erzielen Sie, wenn Sie den Ländercode gefolgt von einem Leerzeichen angeben und den Parameter region code auf den Ländercode festlegen.

Hinweis :Die Funktion „Text Search (New)“ ist im Places SDK for Android ab Version 3.3.0 verfügbar. Weitere Informationen finden Sie unter SDK-Version auswählen. Weitere Informationen zur Verwendung der in Version 4.0.0 hinzugefügten Kotlin APIs finden Sie in der Referenzübersicht.

Text Search-Anfragen

Hinweis :Die Textsuche ist Teil des Places SDK for Android (New) und nicht im Places SDK for Android verfügbar.

Eine Text Search-Anfrage hat folgendes Format:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define latitude and longitude coordinates of the search area.
LatLng southWest = new LatLng(37.38816277477739, -122.08813770258874);
LatLng northEast = new LatLng(37.39580487866437, -122.07702325966572);

// Use the builder to create a SearchByTextRequest object.
final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
  .setMaxResultCount(10)
  .setLocationRestriction(RectangularBounds.newInstance(southWest, northEast)).build();

// Call PlacesClient.searchByText() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchByText(searchByTextRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

In diesem Beispiel haben Sie:

• Legen Sie fest, dass die Feldliste nur Place.Field.ID und Place.Field.DISPLAY_NAME enthält. Das bedeutet, dass die Place-Objekte in der Antwort, die die einzelnen übereinstimmenden Orte darstellen, nur diese beiden Felder enthalten.

• Verwenden Sie SearchByTextRequest.Builder, um ein SearchByTextRequest-Objekt zu erstellen, das die Suche definiert.

  • Legen Sie den Textabfragestring auf „Spicy Vegetarian Food“ fest.

  • Legen Sie die maximale Anzahl der Ergebnisplätze auf 10 fest. Der Standard- und der Höchstwert ist 20.

  • Begrenzen Sie den Suchbereich auf das Rechteck, das durch Breiten- und Längengradkoordinaten definiert ist. Es werden keine Übereinstimmungen außerhalb dieses Bereichs zurückgegeben.

• Fügen Sie ein OnSuccessListener hinzu und rufen Sie die entsprechenden Orte aus dem SearchByTextResponse-Objekt ab.

Hinweis:Weitere Informationen zum Initialisieren von PlacesClient finden Sie unter Places API-Client initialisieren.

Mit einem CancellationToken können Sie versuchen, eine Anfrage an eine der Anfrageklassen (z. B. FetchPlaceRequest) abzubrechen. Die Stornierung erfolgt auf Best-Effort-Basis. Nach dem Einreichen einer Kündigungsanfrage erhalten Sie keine Antwort mehr. Das Ausstellen eines Kündigungstokens ist KEIN Garant dafür, dass eine bestimmte Anfrage storniert wird. Es kann sein, dass Ihnen die Anfrage in Rechnung gestellt wird, auch wenn keine Antwort zurückgegeben wird.

Antworten der Textsuche

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

• 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 sind.

Angenommen, Sie haben in der Anfrage eine Feldliste so definiert:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_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

Die erforderlichen Parameter für SearchByTextRequest sind:

• Feldliste

  Geben Sie an, welche Felder mit Ortsdaten zurückgegeben werden sollen. Übergeben Sie eine Liste von Place.Field-Werten, die die zurückzugebenden Datenfelder angeben. Es gibt keine Standardliste der zurückgegebenen Felder in der Antwort.

  Mithilfe von Feldlisten 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 SKU Text Search (ID Only) aus:

    Place.Field.DISPLAY_NAME, Place.Field.ID, Place.Field.RESOURCE_NAME
    
    Hinweise:

    • Das Feld Place.Field.NAME wurde in Version 4.0 des Places SDK for Android eingestellt. Verwenden Sie stattdessen Place.Field.DISPLAY_NAME.
    • Das Feld RESOURCE_NAME enthält den Namen der Ortsressource im Format places/PLACE_ID. Verwenden Sie DISPLAY_NAME, um auf den Textnamen des Orts zuzugreifen.

  • Die folgenden Felder lösen die SKU Text Search (Basic) aus:

    Place.Field.ACCESSIBILITY_OPTIONS, Place.Field.ADDRESS_COMPONENTS, Place.Field.ADR_FORMAT_ADDRESS, Place.Field.BUSINESS_STATUS, Place.Field.FORMATTED_ADDRESS, Place.Field.GOOGLE_MAPS_URI, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_MASK_URL, Place.Field.LOCATION, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.PRIMARY_TYPE, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, Place.Field.SHORT_FORMATTED_ADDRESS, Place.Field.SUB_DESTINATIONS, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT
    
    Hinweis:Die Felder Place.Field.ADDRESS, Place.Field.ICON_URL, Place.Field.LAT_LNG und Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE wurden in Version 4.0 des Places SDK for Android eingestellt. Verwenden Sie stattdessen Place.Field.FORMATTED_ADDRESS, Place.Field.ICON_MASK_URL, Place.Field.LOCATION und Place.ACCESSIBILITY_OPTIONS. Place.Field.ACCESSIBILITY_OPTIONS ist nur für „Place Details (New)“ verfügbar.

  • Die folgenden Felder lösen die SKU Text 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
    
    Hinweis:Die Felder Place.Field.PHONE_NUMBER und Place.Field.USER_RATINGS_TOTAL wurden in Version 4.0 des Places SDK for Android eingestellt. Verwenden Sie stattdessen Place.Field.INTERNATIONAL_PHONE_NUMBER und Place.USER_RATING_COUNT.

  • Die folgenden Felder lösen die SKU Text 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
  Hinweis:In Version 4.0 des Places SDK for Android wurden mehrere Ortsdatenfelder eingestellt und neue Felder hinzugefügt. Weitere Informationen finden Sie unter Zu den neuen Ortsdatenfeldern im Places SDK for Android 4.0 migrieren .

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

• Textabfrage

  Der Textstring, nach dem gesucht werden soll, z. B. „Restaurant“, „Hauptstraße 60“ oder „beste Sehenswürdigkeiten in San Francisco“. Die API gibt anhand dieses Strings mögliche Übereinstimmungen zurück und sortiert die Ergebnisse nach ihrer wahrgenommenen Relevanz.

  Wenn Sie den Textabfrageparameter festlegen möchten, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setTextQuery() auf.

Optionale Parameter

Verwenden Sie das Objekt SearchByTextRequest, um die optionalen Parameter für Ihre Anfrage anzugeben.

• Eingeschlossener Typ

  Damit werden die Ergebnisse auf Orte beschränkt, die dem in Tabelle A angegebenen Typ entsprechen. Es kann nur ein Typ angegeben werden. Beispiel:

  • setIncludedType("bar")
  • setIncludedType("pharmacy")
  Hinweis : Die Werte in Tabelle B werden nur in der Antwort zurückgegeben. Werte aus Tabelle B können nicht als Filter verwendet werden.

  Wenn Sie den Parameter „included_type“ festlegen möchten, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setIncludedType() auf.

• Standortverzerrung

  Gibt einen Bereich für die Suche an. Dieser Ort dient als Gewichtung. Das bedeutet, dass Ergebnisse in der Nähe des angegebenen Orts zurückgegeben werden können, einschließlich Ergebnissen außerhalb des angegebenen Bereichs.

  Sie können eine Standortbeschränkung oder eine Standortvorlage angeben, aber nicht beides. Eine Standortbeschränkung gibt die Region an, in der sich die Ergebnisse befinden müssen. Bei der Standortgewichtung wird die Region angegeben, in der sich die Ergebnisse wahrscheinlich befinden oder in deren Nähe sie liegen. Beachten Sie, dass die Ergebnisse bei Verwendung der Standortgewichtung auch außerhalb des angegebenen Gebiets liegen können.

  Hinweis : Wenn Sie sowohl die Standortvoreingenommenheit als auch die Standorteinschränkung weglassen, verwendet die API standardmäßig die IP-Voreingenommenheit. Bei der IP-Voreinnahme verwendet die API die IP-Adresse des Geräts, um die Ergebnisse zu beeinflussen.
  Hinweis : Der Parameter locationBias kann überschrieben werden, wenn textQuery einen expliziten Speicherort wie Market in Barcelona enthält. In diesem Fall wird locationBias ignoriert.

  Geben Sie die Region als rechteckigen Darstellungsbereich oder als Kreis an.

  • Ein Kreis wird durch den Mittelpunkt und den Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 liegen (jeweils einschließlich). Beispiel:

    // Define latitude and longitude coordinates of the center of the search area.
    LatLng searchCenter = new LatLng(37.38816277477739, -122.08813770258874);
    
    // Use the builder to create a SearchByTextRequest object.
    // Set the radius of the search area to 500.0 meters.
    final SearchByTextRequest searchByTextRequest = SearchByTextRequest.builder("Spicy Vegetarian Food", placeFields)
      .setMaxResultCount(10)
      .setLocationBias(CircularBounds.newInstance(searchCenter, 500.0)).build();
    

  • Ein Rechteck ist ein Breiten- und Längengrad-Viewport, der durch zwei diagonal gegenüberliegende Tief- und Hochpunkte dargestellt wird. Der Tiefpunkt markiert die Südwestecke des Rechtecks und der Hochpunkt die Nordostecke.

    Ein Darstellungsbereich gilt als geschlossene Region, d. h., er schließt seine Grenze ein. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen und die Längengradgrenzen zwischen -180 und 180 Grad:

    • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
    • Wenn low.longitude > high.longitude ist, ist der Längengradbereich umgekehrt (der Darstellungsbereich schneidet den Längengrad 180).
    • Wenn low.longitude = -180 Grad und high.longitude = 180 Grad ist, enthält der Darstellungsbereich alle Längengrade.
    • Wenn low.longitude = 180 Grad und high.longitude = -180 Grad ist, ist der Längengradbereich leer.
    • Wenn low.latitude > high.latitude ist, ist der Breitengradbereich leer.

    Sowohl „low“ als auch „high“ müssen ausgefüllt sein und das Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

    Ein Beispiel für einen rechteckigen Ansichtsbereich finden Sie unter Text Search-Anfragen.

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

• Standortbeschränkung

  Gibt einen Bereich für die Suche an. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Geben Sie die Region als rechteckigen Darstellungsbereich an. Informationen zum Definieren des Darstellungsbereichs finden Sie in der Beschreibung der Standortvoreingenommenheit.

  Sie können eine Standortbeschränkung oder eine Standortvorlage angeben, aber nicht beides. Stellen Sie sich die Standortbeschränkung als Angabe der Region vor, in der sich die Ergebnisse befinden müssen, und die Standortvorgabe als Angabe der Region, in deren Nähe sich die Ergebnisse befinden müssen, aber auch außerhalb des Gebiets liegen können.

  Hinweis : Wenn Sie sowohl die Standortvoreingenommenheit als auch die Standorteinschränkung weglassen, verwendet die API standardmäßig die IP-Voreingenommenheit. Bei der IP-Voreingenommenheit verwendet die API die IP-Adresse des Geräts, um die Ergebnisse zu beeinflussen.

  Wenn Sie den Parameter für die Standorteinschränkung festlegen möchten, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setLocationRestriction() 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 SearchByTextRequest-Objekts die Methode setMaxResultCount() auf.

• Mindestbewertung

  Die Ergebnisse werden auf diejenigen beschränkt, deren durchschnittliche Nutzerbewertung diesem Limit entspricht oder darüber liegt. Die Werte müssen zwischen 0,0 und 5,0 liegen (jeweils einschließlich) und in Schritten von 0,5 erfolgen. Beispiel: 0, 0,5, 1,0, …, 5,0 Die Werte werden auf die nächste halbe Einheit aufgerundet. Bei einem Wert von 0,6 werden beispielsweise alle Ergebnisse mit einer Bewertung unter 1,0 entfernt.

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

• Jetzt geöffnet

  Bei true werden nur Orte zurückgegeben, die zum Zeitpunkt des Sendens der Anfrage geöffnet haben. Wenn false, werden alle Unternehmen unabhängig vom Öffnungsstatus zurückgegeben. Wenn Sie diesen Parameter auf false festlegen, werden auch Orte zurückgegeben, für die in der Google Places-Datenbank keine Öffnungszeiten hinterlegt sind.

  Wenn Sie den Parameter „Jetzt geöffnet“ festlegen möchten, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setOpenNow() auf.

• Preisniveaus

  Standardmäßig sind in den Ergebnissen Orte enthalten, die Dienstleistungen in allen Preisklassen anbieten. Wenn Sie die Ergebnisse auf Orte in bestimmten Preisklassen beschränken möchten, können Sie eine Liste von Ganzzahlwerten übergeben, die den Preisklassen der Orte entsprechen, die zurückgegeben werden sollen:

  • 1 – Der Ort bietet günstige Dienstleistungen an.
  • 2 – Der Ort bietet Dienstleistungen zu günstigen Preisen an.
  • 3 – Der Ort bietet teure Dienstleistungen an.
  • 4 – Der Ort bietet sehr teure Dienstleistungen an.
  Hinweis : Der Ganzzahlwert von 0, der angibt, dass der Ort kostenlose Dienstleistungen anbietet, kann in einer Antwort enthalten sein, kann aber nicht als Filterwert in einer Anfrage verwendet werden.

  Wenn Sie den Parameter „Preisstufen“ festlegen möchten, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setPriceLevels() auf.

• Rangpräferenz

  Gibt an, wie die Ergebnisse in der Antwort basierend auf dem Abfragetyp sortiert werden:

  • Bei einer kategorischen Suchanfrage wie „Restaurants in New York“ ist SearchByTextRequest.RankPreference.RELEVANCE (Ergebnisse nach Suchrelevanz sortieren) standardmäßig ausgewählt. Sie können die Rangvorgabe auf SearchByTextRequest.RankPreference.RELEVANCE oder SearchByTextRequest.RankPreference.DISTANCE festlegen (Ergebnisse nach Entfernung sortieren).
  • Bei nicht kategorischen Suchanfragen wie „Mountain View, CA“ sollten Sie den Parameter „Rangpräferenz“ nicht festlegen.

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

• Regionscode

  Der Regionscode, der zum Formatieren der Antwort verwendet wird. Er wird als zweistelliger CLDR-Code angegeben. Dieser Parameter kann auch eine Verzerrung der Suchergebnisse bewirken. Es gibt keinen Standardwert.

  Wenn der Name des Landes im Adressfeld in der Antwort mit dem Regionscode übereinstimmt, wird der Ländercode aus der Adresse entfernt.

  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), 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 SearchByTextRequest-Objekts die Methode setRegionCode() auf.

• Strenges Filtern nach Typ

  Wird mit dem Parameter „include type“ verwendet. Wenn „include_type“ auf true festgelegt ist, werden nur Orte zurückgegeben, die den angegebenen Typen entsprechen. Bei false (Standardeinstellung) kann die Antwort Orte enthalten, die nicht den angegebenen Typen entsprechen.

  Wenn Sie den Parameter für die strenge Typfilterung festlegen möchten, rufen Sie die Methode setStrictTypeFiltering() auf, wenn Sie das SearchByTextRequest-Objekt erstellen.