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.
„+1 514-670-8700“

Diese Abfrage enthält eine Telefonnummer. Es werden mehrere Ergebnisse für Orte zurückgegeben, die mit dieser Telefonnummer verknüpft sind.

Text Search-Anfragen

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.

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

    • 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

    • 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

    • 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

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

    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.

    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.

    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.

    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.