Text Search (New)

Plattform auswählen: Android iOS JavaScript Webdienst

Entwickler im Europäischen Wirtschaftsraum (EWR)

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 Adressanfragen in einem automatisierten System zu stellen. Nicht adressbezogene Komponenten des Strings können sowohl mit Unternehmen als auch mit Adressen übereinstimmen. Beispiele für mehrdeutige Adressanfragen sind schlecht formatierte Adressen oder Anfragen, die keine Adresskomponenten wie Unternehmensnamen enthalten. Bei Anfragen wie den ersten beiden Beispielen werden möglicherweise keine Ergebnisse zurückgegeben, sofern kein Standort festgelegt ist, z. B. Region, Standortbeschränkung oder Standortbias.

„Text Search (New)“ ähnelt Nearby Search (New). Der Hauptunterschied zwischen den beiden besteht darin, dass Sie bei der Textsuche (neu) einen beliebigen Suchstring angeben können, während bei der Suche in der Nähe (neu) ein bestimmter Bereich erforderlich ist, in dem gesucht werden soll.

„10 High Street, UK“ oder „123 Main Street, US“ Es gibt mehrere „High Street“-Straßen im Vereinigten Königreich und mehrere „Main Street“-Straßen in den USA. Die Abfrage liefert nur dann die gewünschten Ergebnisse, wenn eine Standortbeschränkung festgelegt ist.
„ChainRestaurant New York“ Mehrere „ChainRestaurant“-Standorte in New York ohne Straßenadresse oder Straßennamen.
„10 High Street, Escher UK“ oder „123 Main Street, Pleasanton US“ 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 ein Unternehmen mit diesem Namen in New York. Es ist keine Straßenadresse erforderlich, um es zu unterscheiden.
„Pizzerien in New York“ Diese Anfrage enthält eine Standortbeschränkung und „Pizzerien“ ist ein genau definierter Ortstyp. Es werden mehrere Ergebnisse zurückgegeben.
„+1 514-670-8700“

Diese Anfrage 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 das folgende 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:

  • Legen Sie die Feldliste so fest, dass sie 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 Textanfrage-String auf „Scharfe vegetarische Speisen“ fest.

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

    • Beschränken Sie den Suchbereich auf das Rechteck, das durch die Breiten- und Längengradkoordinaten definiert wird. 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.

„Text Search“-Antworten

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. Für jeden übereinstimmenden Ort gibt es ein Place-Objekt.

  • Jedes Place-Objekt enthält nur die Felder, die durch die in der Anfrage übergebene Feldliste definiert werden.

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

Diese Feldliste bedeutet, dass jedes Place-Objekt in der Antwort nur die Orts-ID und den Namen jedes übereinstimmenden Orts enthält. 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 des Place-Objekts 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 mit Place.Field-Werten, die die zurückzugebenden Datenfelder angeben. Es gibt keine Standardliste der in der Antwort zurückgegebenen Felder.

    Mit Feldlisten lässt sich verhindern, dass unnötige Daten angefordert werden, was wiederum hilft, unnötige Verarbeitungszeiten und Gebühren zu vermeiden.

    Geben Sie eines oder mehrere der folgenden Felder an:

    • Die folgenden Felder lösen die Text Search Essentials ID Only-SKU aus:

      Place.Field.DISPLAY_NAME*
          * Verwenden Sie diese Funktion anstelle von Place.Field.NAME (in Version 4.0 verworfen).
      Place.Field.ID
      Place.Field.RESOURCE_NAME*
          * Enthält den Ressourcennamen des Orts in folgendem Format: places/PLACE_ID.
           Verwenden Sie DISPLAY_NAME, um auf den Textnamen des Orts zuzugreifen.

    • Die folgenden Felder lösen die Text Search Pro-SKU aus:

      Place.Field.ACCESSIBILITY_OPTIONS*
          Verwenden Sie diese Option anstelle von Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (verworfen).
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS*
          Wird anstelle von Place.Field.ADDRESS (eingestellt) verwendet.
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
          Wird anstelle von Place.Field.ICON_URL (eingestellt) verwendet.
      Place.Field.LOCATION*
          Wird anstelle von Place.Field.LAT_LNG (verworfen) verwendet.
      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 Text Search Enterprise-SKU aus:

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER*
          * Verwenden Sie diese Option anstelle von Place.Field.PHONE_NUMBER, die nicht mehr unterstützt wird.
      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*
          * Verwenden Sie diese Option anstelle von Place.Field.USER_RATINGS_TOTAL, das verworfen wurde.
      Place.Field.WEBSITE_URI

    • Die folgenden Felder lösen die Text Search Enterprise Plus-SKU 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 „field list“ 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 „Sehenswürdigkeiten in San Francisco“. Über die API werden mögliche Übereinstimmungen basierend auf dem String zurückgegeben, die nach erkannter Relevanz sortiert werden.

    Rufen Sie zum Festlegen des Textabfrageparameters die Methode setTextQuery() auf, wenn Sie das SearchByTextRequest-Objekt erstellen.

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 angegebenen Typ entsprechen, der in Tabelle A definiert ist. Es kann nur ein Typ angegeben werden. Beispiel:

    • setIncludedType("bar")
    • setIncludedType("pharmacy")

    Um den eingeschlossenen Typparameter festzulegen, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setIncludedType() auf.

  • Standortbedingte Verzerrung

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

    Sie können eine Standortbeschränkung oder eine Standortgewichtung angeben, aber nicht beides. Bei der Standortbeschränkung wird die Region angegeben, in der sich die Ergebnisse befinden müssen. Bei der Standortgewichtung wird die Region angegeben, in der sich die Ergebnisse wahrscheinlich befinden werden. Beachten Sie, dass Ergebnisse bei der Standortgewichtung auch außerhalb des angegebenen Bereichs 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 Darstellungsbereich für Breiten- und Längengrad, der durch zwei diagonal gegenüberliegende niedrige und hohe Punkte dargestellt wird. Der Tiefpunkt markiert die südwestliche Ecke des Rechtecks und der Hochpunkt die nordöstliche Ecke.

      Ein Darstellungsbereich gilt als geschlossener Bereich, d. h., er umfasst auch seine Grenze. Die Grenzen für den Breitengrad müssen zwischen -90 und 90 Grad liegen (einschließlich), und die Grenzen für den Längengrad müssen zwischen -180 und 180 Grad liegen (einschließlich):

      • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
      • Wenn low.longitude > high.longitude, wird der Längengradbereich umgekehrt (der Darstellungsbereich überschreitet die 180-Grad-Längengradlinie).
      • Wenn low.longitude = -180 Grad und high.longitude = 180 Grad ist, umfasst 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 der Breitengradbereich leer.

      Sowohl „Niedrig“ als auch „Hoch“ müssen ausgefüllt sein und das dargestellte Rechteck darf nicht leer sein. Ein leerer Viewport führt zu einem Fehler.

      Ein Beispiel für ein rechteckiges Viewport finden Sie unter Text Search-Anfragen.

      Wenn Sie den Parameter für die Ortsvoreingenommenheit festlegen möchten, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setLocationBias() 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 Viewports finden Sie in der Beschreibung von Standortbias.

    Sie können eine Standortbeschränkung oder eine Standortgewichtung angeben, aber nicht beides. Bei der Standortbeschränkung wird die Region angegeben, in der sich die Ergebnisse befinden müssen. Beim Standort-Bias wird die Region angegeben, in deren Nähe sich die Ergebnisse befinden müssen, sie können aber auch außerhalb des Bereichs liegen.

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

  • Maximale Anzahl der Ergebnisse

    Gibt die maximale Anzahl der zurückzugebenden Ortsangabe-Ergebnisse an. Muss zwischen 1 und 20 (Standard) liegen.

    Wenn Sie den Parameter für die maximale Anzahl von Ergebnissen festlegen möchten, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setMaxResultCount() auf.

  • Mindestbewertung

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

    Rufen Sie zum Festlegen des Parameters für die Mindestbewertung die Methode setMinRating() beim Erstellen des SearchByTextRequest-Objekts auf.

  • Jetzt geöffnet

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

    Rufen Sie zum Festlegen des Parameters „open now“ (jetzt geöffnet) die Methode setOpenNow() auf, wenn Sie das SearchByTextRequest-Objekt erstellen.

  • Preisniveaus

    Standardmäßig enthalten die Ergebnisse Orte, an denen Dienstleistungen zu allen Preisniveaus angeboten werden. Wenn Sie die Ergebnisse auf Orte mit bestimmten Preisniveaus beschränken möchten, können Sie eine Liste mit Ganzzahlwerten übergeben, die den Preisniveaus der Orte entsprechen, die zurückgegeben werden sollen:

    • 1 – Hier werden günstige Dienstleistungen angeboten.
    • 2 – Hier werden Dienstleistungen zu moderaten Preisen angeboten.
    • 3 – Der Ort bietet teure Dienstleistungen an.
    • 4 – Der Ort bietet sehr teure Dienstleistungen an.

    Rufen Sie zum Festlegen des Parameters „priceLevels“ die Methode setPriceLevels() auf, wenn Sie das SearchByTextRequest-Objekt erstellen.

  • Rangfolge

    Gibt an, wie die Ergebnisse in der Antwort basierend auf dem Typ der Anfrage eingestuft werden:

    • Bei einer kategorischen Anfrage 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 (Ergebnisse nach Entfernung sortieren) festlegen.
    • Bei einer nicht kategorischen Anfrage wie „Mountain View, CA“ empfehlen wir, den Parameter für die Rangfolgepräferenz nicht festzulegen.

    Wenn Sie den Parameter für die Rangfolge festlegen möchten, 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 sich auch auf die Suchergebnisse auswirken. Es gibt keinen Standardwert.

    Wenn der Ländername des Adressfelds in der Antwort mit dem Regionscode übereinstimmt, wird der Ländercode aus der Adresse entfernt.

    Die meisten CLDR-Codes sind mit den ISO 3166-1-Codes identisch. Es gibt jedoch einige Ausnahmen. Die ccTLD des Vereinigten Königreichs ist beispielsweise „uk“ (.co.uk), der ISO 3166-1-Code dagegen „gb“ (technisch für das Land „Vereinigtes Königreich von Großbritannien und Nordirland“). Der Parameter kann sich je nach anwendbarem Recht auf die Ergebnisse auswirken.

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

  • Striktes Filtern nach Typ

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

    Rufen Sie zum Festlegen des Parameters für die strenge Typfilterung die Methode setStrictTypeFiltering() auf, wenn Sie das SearchByTextRequest-Objekt erstellen.