Automatische Vervollständigung (neu)

Plattform auswählen: Android iOS JavaScript Webdienst

Die Funktion „Autocomplete (New)“ gibt Ortsvervollständigungen als Antwort auf eine Anfrage zurück, die einen Textsuchstring und geografische Grenzen, die den Suchbereich steuern, enthält. Mit der automatischen Vervollständigung werden vollständige Wörter und Teilstrings der Eingabe abgeglichen und Ortsnamen, Adressen und Plus Codes aufgelöst. Ihre Anwendung kann Abfragen senden, während der Nutzer tippt, um spontan Vorschläge für Orte und Suchanfragen bereitzustellen.

Beispiel: Sie rufen Autocomplete auf und verwenden als Eingabe einen String, der die Teileingabe „Sicilian piz“ des Nutzers enthält, wobei der Suchbereich auf San Francisco (Kalifornien) beschränkt ist. Die Antwort enthält dann eine Liste von Ortsvorschlägen, die mit dem Suchstring und dem Suchbereich übereinstimmen, z. B. das Restaurant mit dem Namen „Sicilian Pizza Kitchen“.

Die zurückgegebenen Orte sollen dem Nutzer angezeigt werden, um ihn bei der Auswahl des gewünschten Ortes zu unterstützen. Mit einer Place Details (New)-Anfrage können Sie weitere Informationen zu den zurückgegebenen Orten erhalten.

Autocomplete (New)-Anfragen

Die Anwendung kann eine Liste mit vorhergesagten Ortsnamen und/oder Adressen aus der API zur automatischen Vervollständigung abrufen. Dazu wird PlacesClient.findAutocompletePredictions() aufgerufen und ein FindAutocompletePredictionsRequest-Objekt übergeben. Das folgende Beispiel zeigt einen vollständigen Aufruf von PlacesClient.findAutocompletePredictions().

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Autocomplete (New) – Antworten

Die API gibt ein FindAutocompletePredictionsResponse in einem Task-Objekt zurück. FindAutocompletePredictionsResponse enthält eine Liste mit bis zu fünf AutocompletePrediction-Objekten, die vorhergesagte Orte darstellen. Die Liste kann leer sein, wenn es keinen bekannten Ort gibt, der der Abfrage und den Filterkriterien entspricht.

Für jeden vorgeschlagenen Ort können Sie die folgenden Methoden aufrufen, um Ortsdetails abzurufen:

  • getFullText(CharacterStyle) gibt den vollständigen Text einer Ortsbeschreibung zurück. Dies ist eine Kombination aus Primär- und Sekundärtext. Beispiel: Eiffelturm, Avenue Anatole France, Paris, France Außerdem kannst du mit dieser Methode mithilfe von CharacterStyle die Abschnitte der Beschreibung hervorheben, die der Suche entsprechen und einem Stil deiner Wahl entsprechen. Der Parameter CharacterStyle ist optional. Setzen Sie es auf null, wenn Sie keine Hervorhebung benötigen.
  • getPrimaryText(CharacterStyle) gibt den Haupttext zurück, der einen Ort beschreibt. Dies ist normalerweise der Name des Orts. Beispiele: Eiffel Tower und 123 Pitt Street
  • getSecondaryText(CharacterStyle) gibt den Nebentext einer Ortsbeschreibung zurück. Dies ist zum Beispiel als zweite Zeile nützlich, wenn Vorhersagen für die automatische Vervollständigung angezeigt werden. Beispiele: "Avenue Anatole France, Paris, France" und "Sydney, New South Wales".
  • getPlaceId() gibt die Orts-ID des vorgeschlagenen Orts zurück. Eine Orts-ID ist eine ID in Textform, mit der ein Ort eindeutig identifiziert wird. Mit ihr lässt sich das Objekt Place später noch einmal abrufen. Weitere Informationen zu Orts-IDs in Autocomplete finden Sie unter Place Details (New). Allgemeine Informationen zu Orts-IDs finden Sie in der Übersicht zu Orts-IDs.
  • getTypes() gibt die Liste der Ortstypen zurück, die mit diesem Ort verknüpft sind.
  • getDistanceMeters() gibt die Entfernung zwischen diesem Ort und dem in der Anfrage angegebenen Startpunkt in Metern zurück.

Erforderliche Parameter

  • Abfrage

    Die Textzeichenfolge, nach der gesucht werden soll. Geben Sie vollständige Wörter und Teilstrings, Ortsnamen, Adressen und Plus Codes an. Der Dienst „Autocomplete (New)“ gibt mögliche Übereinstimmungen basierend auf diesem String zurück und ordnet die Ergebnisse nach erkannter Relevanz.

    Zum Festlegen des Abfrageparameters rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setQuery() auf.

Optionale Parameter

  • Primäre Typen

    Eine Liste mit bis zu fünf Typwerten des Typs Tabelle A oder Tabelle B, mit der die in der Antwort zurückgegebenen Orte gefiltert werden. Ein Ort muss mit einem der angegebenen Werte des primären Typs übereinstimmen, um in die Antwort aufgenommen zu werden.

    Einem Ort kann nur ein einziger primärer Typ aus dem Typ Tabelle A oder Tabelle B zugeordnet sein. Der primäre Typ kann beispielsweise "mexican_restaurant" oder "steak_house" sein.

    In folgenden Fällen wird die Anfrage mit dem Fehler INVALID_REQUEST abgelehnt:

    • Es sind mehr als fünf Typen angegeben.
    • Alle nicht erkannten Typen wurden angegeben.

    Zum Festlegen des primären Typenparameters rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setTypesFilter() auf.

  • Länder

    Nur Ergebnisse aus der Liste der angegebenen Länder als Liste von bis zu 15 zweistelligen ccTLD-Werten ("top-level domain") einschließen. Wenn keine Angabe gemacht wird, werden keine Einschränkungen auf die Antwort angewendet. So beschränken Sie beispielsweise die Regionen auf Deutschland und Frankreich:

    Wenn Sie sowohl locationRestriction als auch includedRegionCodes angeben, befinden sich die Ergebnisse im Schnittbereich der beiden Einstellungen.

    Wenn Sie den Länderparameter festlegen möchten, rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setCountries() auf.

  • Eingabe-Offset

    Der nullbasierte Unicode-Zeichen-Offset, der die Cursorposition in der Abfrage angibt. Die Cursorposition kann beeinflussen, welche Vorhersagen zurückgegeben werden. Wenn das Feld leer ist, wird standardmäßig die Länge der Abfrage verwendet.

    Zum Festlegen des Eingabe-Offset-Parameters rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setInputOffset() auf.

  • Standortgewichtung oder Standortbeschränkung

    Sie können eine Standortgewichtung oder Standortbeschränkung angeben, aber nicht beides, um den Suchbereich zu definieren. Betrachten Sie die Standortbeschränkung als Angabe der Region, in der sich die Ergebnisse befinden müssen, und die Standortgewichtung gibt die Region an, in der sich die Ergebnisse befinden müssen. Der Hauptunterschied besteht darin, dass bei einer Standortgewichtung weiterhin Ergebnisse außerhalb der angegebenen Region zurückgegeben werden können.

    • Standortgewichtung

      Gibt das Gebiet an, in dem gesucht werden soll. Dieser Standort dient als Verzerrung und nicht als Einschränkung, sodass Ergebnisse außerhalb des angegebenen Bereichs zurückgegeben werden können.

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

    • Standortbeschränkung

      Gibt das Gebiet an, in dem gesucht werden soll. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben.

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

    Geben Sie die Standortgewichtung oder Region zur Standortbeschränkung 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 (einschließlich) liegen. Der Standardwert ist 0,0. Für die Standortbeschränkung müssen Sie den Radius auf einen Wert größer als 0,0 festlegen. Andernfalls gibt die Anfrage keine Ergebnisse zurück.

    • Ein Rechteck ist ein Darstellungsbereich für Breiten- und Längengrad, der als zwei diagonal gegenüberliegende low- und high-Punkte dargestellt wird. Ein Darstellungsbereich gilt als geschlossener Bereich, d. h. er umfasst seine Begrenzung. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad und die Längengradgrenzen zwischen -180 und 180 Grad liegen.

      • Wenn low = high, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
      • Wenn low.longitude > high.longitude ist, wird der Längengradbereich umgekehrt (der Darstellungsbereich kreuzt die 180-Grad-Längenlinie).
      • 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.

      Sowohl low als auch high müssen ausgefüllt werden und das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

  • Ursprung

    Der Startpunkt, von dem aus die lineare Entfernung zum Ziel berechnet werden soll (Zugriff über getDistanceMeters()). Wenn dieser Wert weggelassen wird, wird die direkte Entfernung nicht zurückgegeben. Muss als Breiten- und Längengrad angegeben werden:

    Zum Festlegen des Ursprungsparameters rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setOrigin() auf.

  • Regionscode

    Der zum Formatieren der Antwort verwendete Regionscode, einschließlich der Adressformatierung, angegeben als zweistelliger ccTLD-Wert ("top-level domain"). Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes, es gibt jedoch einige Ausnahmen. So lautet beispielsweise die ccTLD des Vereinigten Königreichs „uk“ (.co.uk) und der ISO 3166-1-Code „gb“ (technisch für die Rechtspersönlichkeit „The United Kingdom of Great Britain and Northern Ireland“).

    Wenn Sie einen ungültigen Regionscode angeben, gibt die API den Fehler INVALID_ARGUMENT zurück. Der Parameter kann sich gemäß geltendem Recht auf Ergebnisse auswirken.

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

  • Sitzungstoken

    Sitzungstokens sind vom Nutzer erstellte Strings, die Aufrufe der automatischen Vervollständigung (New) als "Sitzungen" erfassen. Für die automatische Vervollständigung werden Sitzungstokens verwendet, um die Abfrage- und Auswahlphasen einer Nutzersuche mit automatischer Vervollständigung zu Abrechnungszwecken in einer separaten Sitzung zu gruppieren. Die Sitzung beginnt, wenn der Nutzer mit der Eingabe einer Suchanfrage beginnt, und endet, wenn er einen Ort auswählt. Jede Sitzung kann mehrere Abfragen und eine Ortsauswahl enthalten. Nach Abschluss einer Sitzung ist das Token nicht mehr gültig. Ihre App muss für jede Sitzung ein neues Token generieren. Wir empfehlen, Sitzungstokens für alle programmatischen Sitzungen mit automatischer Vervollständigung zu verwenden. Wenn Sie ein Fragment einbetten oder die automatische Vervollständigung mit einem Intent starten, übernimmt die API dies automatisch.

    Die Autocomplete-Funktion verwendet ein AutocompleteSessionToken, um jede Sitzung zu identifizieren. Zu Beginn jeder neuen Sitzung sollte von Ihrer App ein neues Sitzungstoken übergeben werden. Im nachfolgenden Aufruf von fetchPlace() wird dieses Token dann zusammen mit einer Orts-ID übergeben, um Place Details für den vom Nutzer ausgewählten Ort abzurufen.

    Rufen Sie zum Festlegen des Sitzungstoken-Parameters beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setSessionToken() auf.

    Weitere Informationen finden Sie unter Sitzungstokens.

Beispiele für Autocomplete (New)

Standortbeschränkung und Standortgewichtung verwenden

Bei „Autocomplete (New)“ wird standardmäßig die Gewichtung nach IP-Adresse verwendet, um den Suchbereich zu steuern. Bei der IP-Gewichtung verwendet die API die IP-Adresse des Geräts zur Gewichtung der Ergebnisse. Sie können optional Standorteinschränkungen oder Standortgewichtung verwenden, aber nicht beides, um ein zu durchsuchendes Gebiet anzugeben.

Durch die Standortbeschränkung wird das zu durchsuchende Gebiet angegeben. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Im folgenden Beispiel wird die Standortbeschränkung verwendet, um die Anfrage auf eine kreisförmige Standortbeschränkung mit einem Radius von 5.000 m um San Francisco zu beschränken:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Bei der Standortgewichtung dient der Standort als Gewichtung, d. h., Ergebnisse um den angegebenen Ort herum können zurückgegeben werden, auch solche außerhalb des angegebenen Bereichs. Im nächsten Beispiel wird die Standortgewichtung für die vorherige Anfrage geändert:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Primäre Typen verwenden

Verwenden Sie den Parameter primary types, um die Ergebnisse einer Anfrage auf einen bestimmten Typ einzuschränken, wie in Tabelle A und Tabelle B aufgeführt. Sie können ein Array mit bis zu fünf Werten angeben. Bei Auslassung werden alle Typen zurückgegeben.

Im folgenden Beispiel wird der Abfragestring „Soccer“ angegeben. Dabei wird der primäre Parameter „types“ verwendet, um die Ergebnisse auf Einrichtungen des Typs "sporting_goods_store" zu beschränken:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Wenn Sie den Parameter „primary types“ weglassen, können die Ergebnisse Einrichtungen eines bestimmten Typs enthalten, z. B. "athletic_field".

Ursprung verwenden

Wenn Sie den Parameter origin in Form von Breiten- und Längengradkoordinaten in die Anfrage aufnehmen, nimmt die API die Entfernung zwischen Start und Ziel in die Antwort auf (Zugriff über getDistanceMeters()). In diesem Beispiel wird als Startpunkt das Zentrum von San Francisco festgelegt:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Attribution

Sie können „Autocomplete (New)“ auch ohne Karte verwenden. Wenn Sie jedoch eine Karte anzeigen, muss es eine Google Maps-Karte sein. Wenn Sie Vervollständigungen aus dem Dienst „Autocomplete (New)“ ohne Karte anzeigen, müssen Sie das Google-Logo direkt im Suchfeld bzw. in den Suchergebnissen einfügen. Weitere Informationen findest du unter Google-Logo und Quellenangaben anzeigen.