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.

Neben 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 mit „Text Search (New)“ einen beliebigen Suchstring angeben können, während für „Nearby Search (New)“ ein bestimmter Bereich für die Suche erforderlich ist.

„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:

  • 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 zum Erstellen eines SearchByTextRequest Objekts, das die Suche definiert.

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

    • Legen Sie die maximale Anzahl der zurückzugebenden Orte auf 10 fest. Der Standardwert 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 übereinstimmenden Orte aus dem SearchByTextResponse Objekt ab.

„Text Search“-Antworten

Die SearchByTextResponse Klasse 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 in der in der Anfrage übergebenen Feldliste definiert sind.

In der Anfrage haben Sie beispielsweise eine Feldliste wie folgt 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. Sie können dann 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 Seitenumbrüche der Text Search-Ergebnisse. Diese Methode gibt ein Pagination-Objekt zurück.

Mit der Methode hasNextPage() des Pagination-Objekts können Sie feststellen, ob weitere Ergebnisseiten verfügbar sind. Diese Methode gibt einen booleschen Wert zurück (true oder false).

Wenn 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 die 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 von Place.Field Werten, die die zurückzugebenden Datenfelder angeben. Es gibt keine Standardliste der zurückgegebenen Felder in der Antwort.

    Feldlisten sind eine gute Möglichkeit, unnötige Datenanfragen zu vermeiden. So können Sie 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 Essentials ID Only“ aus:

      Place.Field.DISPLAY_NAME*
          * Verwenden Sie stattdessen Place.Field.NAME (in Version 4.0 eingestellt).
      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 Datenfelder und der zugehörigen SKUs finden Sie unter Felder mit Ortsdaten (neu).

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

      Place.Field.ACCESSIBILITY_OPTIONS*
          Verwenden Sie stattdessen Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE (eingestellt).
      Place.Field.ADDRESS_COMPONENTS
      Place.Field.ADR_FORMAT_ADDRESS
      Place.Field.BUSINESS_STATUS
      Place.Field.FORMATTED_ADDRESS*
          Verwenden Sie stattdessen Place.Field.ADDRESS (eingestellt).
      Place.Field.GOOGLE_MAPS_URI
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
          Verwenden Sie stattdessen Place.Field.ICON_URL (eingestellt).
      Place.Field.LOCATION*
          Verwenden Sie stattdessen Place.Field.LAT_LNG (eingestellt).
      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 Datenfelder und der zugehörigen SKUs finden Sie unter Felder mit Ortsdaten (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 stattdessen Place.Field.PHONE_NUMBER, das eingestellt 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 eingestellt wurde.
      Place.Field.WEBSITE_URI

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

    • Die folgenden Felder lösen die SKU „Text Search Enterprise Plus“ 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 Datenfelder und der zugehörigen SKUs finden Sie unter Felder mit Ortsdaten (neu).

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

  • Textabfrage

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

    Rufen Sie zum Festlegen des Suchparameters für die Textabfrage die setTextQuery()-Methode auf, wenn Sie das SearchByTextRequest-Objekt erstellen.

Optionale Parameter

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

  • Eingeschlossener Typ

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

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

    Rufen Sie zum Festlegen des Parameters für den eingeschlossenen Typ die setIncludedType()-Methode auf, wenn Sie das SearchByTextRequest-Objekt erstellen.

  • Standortgewichtung

    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 eine Standorteinschränkung oder eine Standortgewichtung angeben, aber nicht beides. Bei der Standorteinschränkung geben Sie die Region an, in der sich die Ergebnisse befinden müssen. Bei der Standortgewichtung geben Sie die Region an, in der sich die Ergebnisse wahrscheinlich befinden oder in der Nähe liegen. Wenn Sie die Standortgewichtung verwenden, können die Ergebnisse jedoch auch außerhalb des angegebenen Bereichs liegen.

    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 50000,0 liegen (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 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 Hochpunkt die nordöstliche Ecke des Rechtecks.

      Ein Darstellungsbereich gilt als geschlossene Region, d. h., er umfasst auch seine Grenze. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen (einschließlich) und die Längengradgrenzen müssen zwischen -180 und 180 Grad liegen (einschließlich):

      • Wenn low = high, 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, umfasst der Darstellungsbereich alle Längengrade.
      • Wenn low.longitude = 180 Grad und high.longitude = -180 Grad, ist der Längengradbereich leer.
      • Wenn low.latitude > high.latitude, ist der Breitengradbereich leer.

      Sowohl „low“ als auch „high“ müssen ausgefüllt sein und das dargestellte Rechteck 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.

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

  • 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 der Standortgewichtung.

    Sie können eine Standorteinschränkung oder eine Standortgewichtung angeben, aber nicht beides. Bei der Standorteinschränkung geben Sie die Region an, in der sich die Ergebnisse befinden müssen. Bei der Standortgewichtung geben Sie die Region an, in der sich die Ergebnisse befinden müssen, sie können aber auch außerhalb des Bereichs liegen.

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

  • Maximale Anzahl der Ergebnisse

    Gibt die maximale Anzahl der zurückzugebenden Orts-Ergebnisse an. Muss zwischen 1 und 20 (Standardwert) liegen (einschließlich).

    Rufen Sie zum Festlegen des Parameters für die maximale Anzahl der Ergebnisse die setMaxResultCount()-Methode auf, wenn Sie das SearchByTextRequest-Objekt erstellen.

  • Mindestbewertung

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

    Rufen Sie zum Festlegen des Parameters für die Mindestbewertung die setMinRating() Methode auf, wenn Sie das SearchByTextRequest Objekt erstellen.

  • Jetzt geöffnet

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

    Rufen Sie zum Festlegen des Parameters für „Jetzt geöffnet“ die setOpenNow()-Methode auf, wenn Sie das SearchByTextRequest-Objekt erstellen.

  • Preisniveaus

    Standardmäßig enthalten die Ergebnisse Orte, die Dienste zu allen Preisniveaus anbieten. Wenn Sie die Ergebnisse auf Orte mit bestimmten Preisniveaus beschränken möchten, können Sie eine Liste von Ganzzahlwerten übergeben, die den Preisniveaus der Orte entsprechen, die Sie zurückgeben möchten:

    • 1 - Der Ort bietet kostengünstige Dienste an.
    • 2 - Der Ort bietet Dienste zu moderaten Preisen an.
    • 3 - Der Ort bietet teure Dienste an.
    • 4 - Der Ort bietet sehr teure Dienste an.

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

  • Rangfolge

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

    • Bei einer kategorialen Abfrage wie "Restaurants in New York City" ist SearchByTextRequest.RankPreference.RELEVANCE (Ergebnisse nach Suchrelevanz einstufen) die Standardeinstellung. Sie können die Rangfolge auf SearchByTextRequest.RankPreference.RELEVANCE oder SearchByTextRequest.RankPreference.DISTANCE (Ergebnisse nach Entfernung einstufen) festlegen.
    • Bei einer nicht kategorialen Abfrage wie "Mountain View, CA" empfehlen wir die Einstellung des Parameters für die Rangfolge nicht festzulegen.

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

  • Regionscode

    Der Regionscode, der zum Formatieren der Antwort verwendet wird, angegeben als CLDR-Code mit zwei Zeichen. 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. So lautet beispielsweise die ccTLD des Vereinigten Königreichs ist „uk“ (.co.uk), der ISO 3166-1-Code dagegen „gb“ (technisch für die Einheit „Vereinigtes Königreich Großbritannien und Nordirland“). Der Parameter kann sich aufgrund geltender Gesetze auf die Ergebnisse auswirken.

    Rufen Sie zum Festlegen des Parameters für den Regionscode die setRegionCode() Methode auf, wenn Sie das SearchByTextRequest Objekt erstellen.

  • Strikte Typfilterung

    Wird mit dem Parameter für den eingeschlossenen Typ verwendet. Wenn auf true gesetzt, werden nur Orte zurückgegeben, die den angegebenen Typen entsprechen, die durch den eingeschlossenen Typ angegeben werden. Wenn false (Standardeinstellung), kann die Antwort Orte enthalten, die nicht den angegebenen Typen entsprechen.

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