Text Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Mit „Text Search (New)“ werden Informationen zu mehreren Orten auf Grundlage eines Strings zurückgegeben, z. B. „Pizza in New York“, „Schuhgeschäfte in der Nähe von Ottawa“ oder „Hauptstraße 123“. Der Dienst gibt eine Liste von Orten zurück, die dem Textstring und der festgelegten Standortgewichtung entsprechen.

Der Dienst ist besonders nützlich für mehrdeutige Adressabfragen in einem automatisierten System. Dabei können nicht adressierte Komponenten des Strings sowohl mit Unternehmen als auch mit Adressen übereinstimmen. Beispiele für mehrdeutige Adressabfragen sind schlecht formatierte Adressen oder Anfragen, die Nicht-Adresskomponenten wie Unternehmensnamen enthalten. Anfragen wie in den ersten beiden Beispielen können null Ergebnisse zurückgeben, es sei denn, ein Standort – wie eine Region, die Standortbeschränkung oder die Standortgewichtung – ist festgelegt.

„Text Search (New)“ ist mit Nearby Search (New) vergleichbar. Der Hauptunterschied zwischen den beiden besteht darin, dass Sie mit „Text Search (New)“ einen beliebigen Suchstring angeben können, während „Nearby Search (New)“ einen bestimmten Bereich für die Suche erfordert.

„10 High Street, UK“ oder „123 Main Street, US“	Mehrere "High Streets" im Vereinigten Königreich und mehrere "Main Streets" in den USA Die Abfrage gibt nur dann die gewünschten Ergebnisse zurück, wenn eine Standortbeschränkung festgelegt ist.
„ChainRestaurant New York“	Mehrere „ChainRestaurant“-Standorte in New York, aber weder Adresse noch Straßenname sind vorhanden.
„10 High Street, Escher UK“ oder „123 Main Street, Pleasanton US“	Nur eine "High Street" in der Stadt Escher im Vereinigten Königreich und nur eine "Main Street" in Pleasanton, Kalifornien.
„UniqueRestaurantName New York“	Nur eine Einrichtung mit diesem Namen in New York. Zur Unterscheidung ist keine Adresse erforderlich.
„pizzerien in new york“	Diese Abfrage enthält die Standortbeschränkung und „Pizzerias“ ist ein klar definierter Ortstyp. Es werden mehrere Ergebnisse zurückgegeben.
„[phone]“	Diese Abfrage enthält eine Telefonnummer. Für Orte, die mit dieser Telefonnummer verknüpft sind, werden mehrere Ergebnisse zurückgegeben. Hinweis : Die besten Ergebnisse bei der Suche nach einer Telefonnummer erhalten Sie, wenn Sie die Landesvorwahl gefolgt von einem Leerzeichen angeben und den Parameter region code auf die entsprechende Landesvorwahl setzen.

Hinweis : „Text Search (New)“ ist im Places SDK for Android 3.3.0 und höher verfügbar. Weitere Informationen findest du unter SDK-Version auswählen.

Text Search-Anfragen

Hinweis : „Text Search“ ist Teil des Places SDK for Android (New) und nicht im Places SDK for Android verfügbar.

Eine „Text Search“-Anfrage hat das folgende Format:

// Specify the list of fields to return.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.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 führen Sie folgende Schritte aus:

• Lege die Feldliste so fest, dass sie nur Place.Field.ID und Place.Field.NAME enthält. Das bedeutet, dass die Place-Objekte in der Antwort, die die einzelnen übereinstimmenden Orte repräsentieren, nur diese beiden Felder enthalten.

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

  • Setzen Sie den Textabfragestring auf „Scharfes vegetarisches Essen“.

  • Legen Sie die maximale Anzahl der Ergebnisorte auf 10 fest. Der Standardwert und der Höchstwert sind 20.

  • Beschränken Sie den Suchbereich auf das durch Breiten- und Längengrade definierte Rechteck. Es werden keine Übereinstimmungen außerhalb dieses Bereichs zurückgegeben.

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

Sie können ein CancellationToken verwenden, um eine Anfrage an eine der Anfrageklassen (z. B. FetchPlaceRequest) abzubrechen. Die Stornierung erfolgt auf Best-Effort-Basis. Nachdem eine Kündigungsanfrage gestellt wurde, wird keine Antwort mehr zurückgegeben. Das Ausstellen eines Kündigungstokens garantiert NICHT, dass eine bestimmte Anfrage abgebrochen wird. Die Anfrage kann Ihnen auch dann in Rechnung gestellt werden, wenn keine Antwort zurückgegeben wird.

Text Search-Antworten

Die Klasse SearchByTextResponse stellt die Antwort einer Suchanfrage dar. Ein SearchByTextResponse-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 von der Feldliste definiert wurden, die in der Anfrage übergeben wurde.

In der Anfrage haben Sie beispielsweise eine Feldliste so definiert:

// Specify the list of fields to return.
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

Die erforderlichen Parameter für SearchByTextRequest sind:

• Liste der Felder

  Geben Sie an, welche Felder mit Ortsdaten zurückgegeben werden sollen. Übergeben Sie eine Liste von Place.Field-Werten und geben Sie die Datenfelder an, die zurückgegeben werden sollen. Die Antwort enthält keine Standardliste der zurückgegebenen Felder.

  Feldlisten sind eine gute Strategie, 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 „Text Search (ID Only)“ aus:

    Place.Field.ID, Place.Field.NAME

  • Die folgenden Felder lösen die SKU „Text 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.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

  • Die folgenden Felder lösen die SKU „Text 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 „Text 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

  Zum Festlegen des Feldlistenparameters rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setPlaceFields() auf.

• Textabfrage

  Der Textstring, nach dem gesucht werden soll, z. B. „Restaurant“, „Hauptstraße 123“ oder „beste Sehenswürdigkeit in San Francisco“. Die API gibt mögliche Übereinstimmungen basierend auf diesem String zurück und ordnet die Ergebnisse nach erkannter Relevanz.

  Um den Textabfrageparameter festzulegen, 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.

• Enthaltener Typ

  Beschränkt die Ergebnisse auf Orte, die dem in Tabelle A definierten 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. Sie können in Tabelle B keine Werte als Filter verwenden.

  Zum Festlegen des enthaltenen Typparameters rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setIncludedType() auf.

• Standortgewichtung

  Gibt das Gebiet an, in dem gesucht werden soll. Dieser Standort dient als Verzerrung, d. h., Ergebnisse um den angegebenen Standort herum können zurückgegeben werden, auch solche außerhalb des angegebenen Bereichs.

  Sie können die Standortbeschränkung oder die Standortgewichtung festlegen, aber nicht beides. Betrachten Sie die Standortbeschränkung als Angabe der Region, in der sich die Ergebnisse befinden müssen, und die Standortgewichtung gibt die Region an, in der sich die Ergebnisse in der Nähe befinden müssen, aber außerhalb des Gebiets liegen können.

  Hinweis : Wenn Sie sowohl die Standortgewichtung als auch die Standortbeschränkung weglassen, verwendet die API standardmäßig die Quellengewichtung nach IP-Adresse. Bei der IP-Gewichtung verwendet die API die IP-Adresse des Geräts zur Gewichtung der Ergebnisse.
  Hinweis : Der Parameter locationBias kann überschrieben werden, wenn textQuery einen expliziten Ort wie Market in Barcelona enthält. In diesem Fall wird locationBias ignoriert.

  Legen Sie den Bereich als rechteckigen Darstellungsbereich oder als Kreis fest.

  • Ein Kreis wird durch einen Mittelpunkt und einen Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 (einschließlich) liegen. 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 Darstellungsbereich mit Breiten- und Längengrad, der als zwei diagonal gegenüberliegende niedrige und hohe Punkte dargestellt wird. Der Tiefpunkt stellt die südwestliche Ecke des Rechtecks und der höchste Punkt die nordöstliche Ecke des Rechtecks dar.

    Ein Darstellungsbereich gilt als geschlossener Bereich, d. h. er umfasst seine Begrenzung. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad und die Längengradgrenzen zwischen -180 und 180 Grad liegen.

    • Wenn low = high, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
    • Ist low.longitude > high.longitude, wird der Längengradbereich umgekehrt (der Darstellungsbereich kreuzt die 180-Grad-Längenlinie).
    • 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.

    Die Werte für „Niedrig“ und „Hoch“ müssen ausgefüllt werden. Das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

    Informationen zu einem rechteckigen Darstellungsbereich finden Sie beispielsweise unter Text Search-Anfragen.

    Um den Parameter für die Standortgewichtung festzulegen, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setLocationBias() auf.

• Standortbeschränkung

  Gibt das Gebiet an, in dem gesucht werden soll. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Legen Sie den Bereich als rechteckigen Darstellungsbereich fest. Informationen zum Definieren des Darstellungsbereichs finden Sie in der Beschreibung der Standortverzerrung.

  Sie können die Standortbeschränkung oder die Standortgewichtung festlegen, aber nicht beides. Betrachten Sie die Standortbeschränkung als Angabe der Region, in der sich die Ergebnisse befinden müssen, und die Standortgewichtung gibt die Region an, in der sich die Ergebnisse in der Nähe befinden müssen, aber außerhalb des Gebiets liegen können.

  Hinweis : Wenn Sie sowohl die Standortgewichtung als auch die Standortbeschränkung weglassen, verwendet die API standardmäßig die Quellengewichtung nach IP-Adresse. Bei der IP-Gewichtung verwendet die API die IP-Adresse des Geräts zur Gewichtung der Ergebnisse.

  Um den Parameter für die Standortbeschränkung festzulegen, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setLocationRestriction() 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 SearchByTextRequest-Objekts die Methode setMaxResultCount() auf.

• Mindestbewertung

  Beschränkt die Ergebnisse auf Nutzer, deren durchschnittliche Nutzerbewertung größer oder gleich dieser Grenze ist. Die Werte müssen zwischen 0,0 und einschließlich 5,0 in Schritten von 0,5 liegen. Beispiel: 0, 0,5, 1,0, ... , 5,0 (jeweils einschließlich). Die Werte werden auf die nächsten 0,5 aufgerundet. Bei einem Wert von 0,6 werden beispielsweise alle Ergebnisse mit einer Bewertung unter 1,0 ausgeschlossen.

  Um den Parameter für die Mindestbewertung festzulegen, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setMinRating() auf.

• Jetzt geöffnet

  Bei true werden nur die Orte zurückgegeben, die beim Senden der Abfrage geöffnet haben. Bei false werden alle Unternehmen unabhängig vom Öffnungsstatus zurückgegeben. Wenn Sie diesen Parameter auf false festlegen, werden Orte zurückgegeben, für die in der Google Places-Datenbank keine Öffnungszeiten angegeben sind.

  Zum Festlegen des Parameters „Jetzt öffnen“ rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setOpenNow() auf.

• Preisstufen

  Standardmäßig enthalten die Ergebnisse Orte, an denen Dienstleistungen aller Preisstufen angeboten werden. Wenn Sie die Ergebnisse auf Orte mit bestimmten Preisstufen beschränken möchten, können Sie eine Liste ganzzahliger Werte übergeben, die den Preisstufen der Orte entsprechen, die Sie zurückgeben möchten:

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

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

• Rangfolgeneinstellung

  Gibt an, wie die Ergebnisse in der Antwort basierend auf der Art der Suchanfrage eingestuft werden:

  • Für eine kategoriale Suchanfrage wie „Restaurants in New York City“ ist SearchByTextRequest.RankPreference.RELEVANCE (Ergebnisse nach Suchrelevanz sortieren) die Standardeinstellung. Sie können die Rangfolge auf SearchByTextRequest.RankPreference.RELEVANCE oder SearchByTextRequest.RankPreference.DISTANCE festlegen (Ergebnisse nach Entfernung sortieren).
  • Für eine nicht kategoriale Abfrage wie „Mountain View, CA“ empfehlen wir, den Parameter für die Rangeinstellung nicht zu verwenden.

  Zum Festlegen des Parameters für die Rangeinstellung rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setRankPreference() auf.

• Regionscode

  Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger CLDR-Code. Dieser Parameter kann auch zu Verzerrungen der Suchergebnisse führen. Es gibt keinen Standardwert.

  Wenn der Ländername des Adressfelds in der Antwort mit dem Regionscode übereinstimmt, wird der Ländercode in der Adresse 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 SearchByTextRequest-Objekts die Methode setRegionCode() auf.

• Strikte Filterung

  Wird mit dem Parameter „Einschließen“-Typ verwendet. Wenn true festgelegt ist, werden nur Orte zurückgegeben, die den angegebenen Typen entsprechen, die durch den Typ „Einschließen“ angegeben wurden. Wenn der Standardwert false ist, kann die Antwort Orte enthalten, die nicht den angegebenen Typen entsprechen.

  Um den strikten Typfilterungsparameter festzulegen, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setStrictTypeFiltering() auf.