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.

Zusätzlich zu den erforderlichen Parametern unterstützt Text Search (New) die Verfeinerung von Abfragen mit optionalen Parametern, um bessere Ergebnisse zu erzielen.

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

„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 haben Sie Folgendes getan:

  • Legen Sie die Feldliste so fest, dass nur Place.Field.ID und Place.Field.DISPLAY_NAME enthalten sind. 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 „Scharfes vegetarisches Essen“ fest.

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

    • Der Suchbereich wird auf das Rechteck beschränkt, das durch die Breiten- und Längengradkoordinaten definiert ist. Es werden keine Übereinstimmungen außerhalb dieses Bereichs zurückgegeben.

  • Fügen Sie einen OnSuccessListener hinzu und rufen Sie die passenden 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, mit einem Place-Objekt pro übereinstimmendem Ort.

  • Jedes Place-Objekt enthält nur die Felder, die in der Feldliste definiert sind, 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.DISPLAY_NAME);

Diese Feldliste bedeutet, dass jedes Place-Objekt in der Antwort nur die Orts-ID und den Namen des jeweiligen ü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.

Seitenumbruch

Die Klasse SearchByTextResponse von Text Search bietet über die Methode getPagination() Zugriff auf die Paginierung von Suchergebnissen. Diese Methode gibt ein Pagination-Objekt zurück.

Verwenden Sie die Methode hasNextPage() des Pagination-Objekts, um festzustellen, ob weitere Ergebnisseiten verfügbar sind. Diese Methode gibt einen booleschen Wert zurück (true oder false).

Solange hasNextPage() „true“ zurückgibt, rufen Sie die Methode fetchNextPage() auf, um die nächste Ergebnisseite abzurufen.

Im folgenden Beispiel wird gezeigt, wie Sie prüfen, ob eine nächste Seite verfügbar ist, und diese Seite dann laden.

Kotlin

val searchByTextRequest =
      searchByTextRequest("restaurants", Arrays.asList(Place.Field.NAME)) {
        maxResultCount = 10
      }

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)   
    .addOnSuccessListener {response: SearchByTextResponse ->
        val places = response.places

        val pagination = response.pagination

        if (pagination.hasNextPage()) {
            pagination.setPageSize(20)
            pagination.fetchNextPage()
                    .addOnSuccessListener { nextPageResponse ->
                          val nextPagePlaces = nextPageResponse.getPlaces()
                    }
                    .addOnFailureListener {// Handle error with given status code}
        }
}
.addOnFailureListener {
// TODO: Handle error with given status code.
exception -> {
          exception.printStackTrace();
        }
}

Java

SearchByTextRequest searchByTextRequest =
  SearchByTextRequest.builder("restaurants", Arrays.asList(Place.Field.NAME)).setMaxResultCount(10).build();

// using pagination object (Preferred)
placesClient.searchByText(searchByTextRequest)
  .addOnSuccessListener((response) -> {
    List<Place> places = response.getPlaces();
    Log.i(TAG, "Places result: " + places);

    Pagination pagination =
      response.getPagination();

    if (pagination.hasNextPage()) {
      pagination.setPageSize(20); // change the page size from 10 to 20
      pagination.fetchNextPage()
    	  .addOnSuccessListener((nextPageResponse) -> {
            List<Place> nextPagePlaces = nextPageResponse.getPlaces();
            Log.i(TAG, "Next page places result: " + nextPagePlaces);
        });
    }
  })
  .addOnFailureListener((exception) -> {
    if (exception instanceof ApiException) {
    	// Handle error with given status code
    }
  });

Erforderliche Parameter

Die erforderlichen Parameter für SearchByTextRequest sind:

  • Feldliste

    Geben Sie an, welche Datenfelder 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 zurückgegebenen Felder in der Antwort.

    Feldlisten sind eine gute Designpraxis, um sicherzustellen, dass Sie keine unnötigen Daten anfordern. So lassen sich unnötige Verarbeitungszeiten und Abrechnungsgebühren vermeiden.

    Geben Sie eines oder mehrere der folgenden Felder an:

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

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

      Eine vollständige Liste der Felder und der zugehörigen SKUs finden Sie unter Ortsdatenfelder (neu).

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

      Place.Field.ACCESSIBILITY_OPTIONS*
          Verwenden Sie stattdessen Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (verworfen).
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS*
          Verwenden Sie diesen Wert anstelle von Place.Field.ADDRESS (eingestellt).
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
          Verwenden Sie dies anstelle von Place.Field.ICON_URL (eingestellt).
      Place.Field.LOCATION*
          Verwenden Sie dies anstelle von Place.Field.LAT_LNG (verworfen).
      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

      Eine vollständige Liste der Felder und der zugehörigen SKUs finden Sie unter Ortsdatenfelder (neu).

    • Die folgenden Felder lösen die SKU „Text Search Enterprise“ 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, das verworfen wurde.
      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 stattdessen Place.Field.USER_RATINGS_TOTAL, das verworfen wurde.
      Place.Field.WEBSITE_URI

      Eine vollständige Liste der Felder und der zugehörigen SKUs finden Sie unter Ortsdatenfelder (neu).

    • 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

      Eine vollständige Liste der Felder und der zugehörigen SKUs finden Sie unter Ortsdatenfelder (neu).

    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 „Sehenswürdigkeiten in Berlin“. Die API gibt mögliche Übereinstimmungen basierend auf dem String zurück, die nach erkannter Relevanz sortiert werden.

    Wenn Sie den Suchparameter für die Textabfrage 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 eingeschrä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 für den eingeschlossenen Typ festlegen möchten, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setIncludedType() auf.

  • Standortverzerrung

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

    Sie können entweder 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 oder in deren Nähe sie sich befinden. Beachten Sie, dass bei der Standortgewichtung Ergebnisse auch außerhalb des angegebenen Bereichs liegen können.

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

    • Ein Kreis wird durch einen Mittelpunkt und einen Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 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 durch zwei diagonal gegenüberliegende Tief- und Hochpunkte dargestellt wird. Der Tiefpunkt markiert die südwestliche Ecke des Rechtecks und der Höchstpunkt die nordöstliche Ecke.

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

      • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
      • Wenn low.longitude > high.longitude, wird der Längengradbereich invertiert (der Darstellungsbereich kreuzt den 180. Längengrad).
      • 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 der niedrige als auch der hohe Wert müssen angegeben werden und das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

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

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

  • Standorteinschrä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 von Standortgewichtung.

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

    Rufen Sie zum Festlegen des Parameters für die Standortbeschränkung die Methode setLocationRestriction() auf, wenn Sie das SearchByTextRequest-Objekt erstellen.

  • Maximale Anzahl der Ergebnisse

    Gibt die maximale Anzahl der zurückzugebenden Ortsergebnisse 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 Limit 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. Die Werte werden auf die nächsten 0,5 aufgerundet. Beispiel: Ein Wert von 0,6 entfernt alle Ergebnisse mit einer Bewertung von weniger als 1,0.

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

  • Jetzt geöffnet

    Wenn true, werden nur die Orte zurückgegeben, die beim Senden 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 „openNow“ festlegen möchten, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setOpenNow() auf.

  • Preisniveau

    Standardmäßig werden Orte mit Dienstleistungen aller Preisstufen angezeigt. Wenn Sie die Ergebnisse auf Orte mit bestimmten Preisstufen beschränken möchten, können Sie eine Liste mit Ganzzahlwerten übergeben, die den Preisstufen der Orte entsprechen, die zurückgegeben werden sollen:

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

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

  • Rangfolge-Einstellung

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

    • Bei einer kategorischen Suchanfrage wie „Restaurants in New York City“ ist SearchByTextRequest.RankPreference.RELEVANCE (Ergebnisse nach Suchrelevanz sortieren) die Standardeinstellung. Sie können die Rangfolgepräferenz auf SearchByTextRequest.RankPreference.RELEVANCE oder SearchByTextRequest.RankPreference.DISTANCE (Ergebnisse nach Entfernung sortieren) festlegen.
    • Bei einer nicht kategorischen Abfrage 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 Regionscode, der zum Formatieren der Antwort verwendet wird, 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 in der Adresse weggelassen.

    Die meisten CLDR-Codes sind mit den ISO 3166-1-Codes identisch, es gibt jedoch einige Ausnahmen. So lautet beispielsweise die ccTLD des Vereinigten Königreichs „uk“ (.co.uk), der ISO-3166-1-Code dagegen „gb“ (technisch gesehen für das Vereinigte Königreich Großbritannien und Nordirland). Der Parameter kann sich je nach anwendbarem Recht auf die 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 Typfilterung

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

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