Text Search (New)

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

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-Adresskomponenten wie Unternehmensnamen enthalten. Anfragen wie in den ersten beiden Beispielen werden möglicherweise null zurückgegeben, wenn kein Standort festgelegt ist, z. B. Region, Standortbeschränkung oder Standortgewichtung.

„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 „Nearby Search (New)“ einen bestimmten Bereich für die Suche erfordert.

„Hauptstraße 10, Deutschland“ oder „Hauptstraße 12, USA“ 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; keine Adresse und kein Straßenname.
„10 High Street, Escher UK“ oder „123 Main Street, Pleasanton US“ In der britischen Stadt Escher gibt es nur eine "High Street" und in der US-amerikanischen Stadt Pleasanton, nur eine "Main Street".
„UniqueRestaurantName New York“ Nur ein Unternehmen mit diesem Namen in New York; keine Adresse zur Unterscheidung erforderlich.
„pizza restaurants in new york“ Diese Abfrage enthält die Standortbeschränkung. „Pizzarestaurants“ ist ein klar definierter Ortstyp. Es werden mehrere Ergebnisse zurückgegeben.
„+49 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 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:

  • Legen Sie in der Feldliste nur Place.Field.ID und Place.Field.NAME fest. Das bedeutet, dass die Place-Objekte in der Antwort, die jeden übereinstimmenden Ort 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 von Ergebnisorten auf 10 fest. Die Standardeinstellung und der Höchstwert sind 20.

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

  • Füge ein OnSuccessListener hinzu und rufe die übereinstimmenden Orte aus dem Objekt SearchByTextResponse ab.

Text Search-Antworten

Die Klasse SearchByTextResponse stellt die Antwort auf eine Suchanfrage dar. Ein SearchByTextResponse-Objekt enthält Folgendes:

  • Eine Liste mit 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 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 übereinstimmenden Orts enthält. Sie können dann die Methoden Place.getId() und Place.getName() verwenden, um auf diese Felder in jedem Place-Objekt zuzugreifen.

Weitere Beispiele für den Zugriff auf Daten in einem Place-Objekt finden Sie unter Auf Place-Objektdatenfelder 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, in denen die Datenfelder festgelegt werden, die zurückgegeben werden sollen. In der Antwort gibt es keine Standardliste der zurückgegebenen Felder.

    Mithilfe von Feldlisten können Sie verhindern, dass unnötige Daten angefordert werden. So lassen sich unnötige Verarbeitungszeiten und Gebühren vermeiden.

    Geben Sie eines oder mehrere der folgenden Felder an:

    • Durch die folgenden Felder wird die SKU „Text Search (ID Only)“ ausgelöst:

      Place.Field.ID, Place.Field.NAME
    • Durch die folgenden Felder wird die SKU „Text Search (Basic)“ ausgelöst:

      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

    Um den Parameter für die Feldliste festzulegen, 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 „bester Ort 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.

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

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

  • Standortgewichtung

    Gibt einen zu durchsuchenden Bereich an. Dieser Standort dient als Verzerrung, das heißt, dass Ergebnisse rund um den angegebenen Standort 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. Stellen Sie sich die Standortbeschränkung als die Definition der Region vor, in der sich die Ergebnisse befinden müssen, und die Standortgewichtung als die Angabe der Region, in der sich die Ergebnisse in der Nähe befinden müssen, aber außerhalb dieses Bereichs liegen können.

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

    • Ein Kreis wird durch den Mittelpunkt und einen Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50000,0 (jeweils 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 aus Breiten- und Längengrad, der als zwei diagonal gegenüberliegende niedrige und hohe Punkte dargestellt wird. Der Tiefpunkt markiert die südwestliche Ecke des Rechtecks und der höchste Punkt die nordöstliche Ecke des Rechtecks.

      Ein Darstellungsbereich wird als geschlossener Bereich betrachtet, d. h. er enthält seine Begrenzung. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen und die Längengradgrenzen zwischen -180 und 180 Grad (jeweils einschließlich):

      • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
      • Wenn low.longitude > high.longitude ist, wird der Längengradbereich invertiert (der Darstellungsbereich kreuzt die 180-Grad-Längengradlinie).
      • Ist low.longitude = -180 Grad und high.longitude = 180 Grad, 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 „niedrig“ als auch „hoch“ muss ausgefüllt werden und das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

      Für einen rechteckigen Darstellungsbereich siehe 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 einen zu durchsuchenden Bereich 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 Standortbeschränkung oder eine Standortgewichtung angeben, aber nicht beides. Stellen Sie sich die Standortbeschränkung als die Definition der Region vor, in der sich die Ergebnisse befinden müssen, und die Standortgewichtung als die Angabe der Region, in der sich die Ergebnisse in der Nähe befinden müssen, aber außerhalb des Gebiets liegen können können.

    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 (Standardwert) liegen.

    Rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setMaxResultCount() auf, um den Parameter für die maximale Ergebnisanzahl festzulegen.

  • Mindestbewertung

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

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

  • Jetzt geöffnet

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

    Um den Parameter „open now“ festzulegen, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die Methode setOpenNow() auf.

  • Preisstufen

    Standardmäßig umfassen die Ergebnisse Orte, die Dienstleistungen in allen Preisstufen anbieten. Wenn Sie die Ergebnisse auf Orte mit bestimmten Preisstufen beschränken möchten, können Sie eine Liste mit Ganzzahlwerten übergeben, die den Preisstufen für die Orte entsprechen, die zurückgegeben werden sollen:

    • 1: Der Ort bietet preisgünstige Dienstleistungen an.
    • 2 – Place bietet Dienstleistungen zu mäßigen Preisen an.
    • 3: Der Ort bietet teure Dienstleistungen.
    • 4: Der Ort bietet sehr teure Dienstleistungen.

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

  • Rangeinstellung

    Gibt an, wie die Ergebnisse in der Antwort auf Basis des Abfragetyps eingestuft werden:

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

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

  • Regionscode

    Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger CLDR-Code-Wert. Dieser Parameter kann sich auch negativ 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 ISO 3166-1-Codes identisch. Es gibt jedoch einige Ausnahmen. Die ccTLD des Vereinigten Königreichs lautet beispielsweise „uk“ (.co.uk), während der ISO 3166-1-Code „gb“ lautet (technisch für die Rechtspersönlichkeit „The United Kingdom of Great Britain and Northern Ireland“). Der Parameter kann sich gemäß anwendbarem Recht auf Ergebnisse auswirken.

    Um den Regionscode-Parameter festzulegen, rufen Sie beim Erstellen des SearchByTextRequest-Objekts die setRegionCode()-Methode auf.

  • Strikte Typfilterung

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

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