Automatische Vervollständigung (neu)

Plattform auswählen: Android iOS JavaScript Webdienst

„Autocomplete (New)“ gibt Ortsvorschläge in Antwort auf eine Anfrage zurück, die einen Textsuchstring und geografische Grenzen enthält, die den Suchbereich steuern. Die automatische Vervollständigung kann Übereinstimmungen mit vollständigen Wörtern und Teilstrings der Eingabe finden, sodass sich Ortsnamen, Adressen und Plus Codes zuordnen lassen. Ihre Anwendung kann Abfragen senden, während der Nutzer tippt, und schon bei der Eingabe Orts- und Suchvorschläge ausgeben.

Angenommen, Sie rufen die automatische Vervollständigung mit einem String auf, der eine teilweise Nutzereingabe enthält, z. B. „Sicilian piz“, und das Suchgebiet ist auf San Francisco, CA, beschränkt. Die Antwort enthält dann eine Liste mit Ortsvorschlägen, die mit dem Suchstring und dem Suchgebiet übereinstimmen, z. B. das Restaurant „Sicilian Pizza Kitchen“.

Die zurückgegebenen Ortsvorschläge sollen dem Nutzer dabei helfen, den gewünschten Ort auszuwählen. Sie können eine Place Details (New)-Anfrage stellen, um weitere Informationen zu den zurückgegebenen Ortsvorschlägen zu erhalten.

Autocomplete (New)-Anfragen

Ihre App kann eine Liste der vorgeschlagenen Ortsnamen und/oder Adressen aus der Autocomplete API abrufen, indem Sie PlacesClient.findAutocompletePredictions() aufrufen 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());
        })
    );

Antworten mit automatischer Vervollständigung (neu)

Die API gibt eine FindAutocompletePredictionsResponse in einem Task zurück. Das FindAutocompletePredictionsResponse-Objekt enthält eine Liste mit bis zu fünf AutocompletePrediction-Objekten, die die vorgeschlagenen Orte darstellen. Die Liste kann leer sein, wenn kein Ort bekannt ist, der der Suchanfrage und den Filterkriterien entspricht.

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

  • getFullText(CharacterStyle) gibt den vollständigen Text einer Ortsbeschreibung zurück. Dies ist eine Kombination aus primärem und sekundärem Text. Beispiel: Eiffelturm, Avenue Anatole France, Paris, Frankreich Außerdem können Sie mit dieser Methode die Abschnitte der Beschreibung, die mit der Suche übereinstimmen, mit CharacterStyle in einem beliebigen Stil hervorheben. Der Parameter CharacterStyle ist optional. Legen Sie den Wert auf „null“ fest, wenn keine Hervorhebung erforderlich ist.
  • getPrimaryText(CharacterStyle) gibt den Haupttext zurück, in dem ein Ort beschrieben wird. Das ist normalerweise der Name des Orts. Beispiele: Eiffelturm und 123 Pitt Street.
  • getSecondaryText(CharacterStyle) gibt den Zusatztext einer Ortsbeschreibung zurück. Das ist beispielsweise als zweite Zeile bei der Anzeige von automatischen Vervollständigungsvorschlägen nützlich. Beispiele: Avenue Anatole France, Paris, Frankreich und Sydney, New South Wales.
  • getPlaceId() gibt die Orts-ID des vorgeschlagenen Orts zurück. Die Orts-ID ist eine Kennung in Textform, die einen Ort eindeutig definiert. Sie können sie verwenden, um das Place-Objekt später noch einmal abzurufen. Weitere Informationen zu Orts-IDs in Autocomplete finden Sie unter Place Details (neu). 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 Luftlinie zwischen diesem Ort und dem in der Anfrage angegebenen Startpunkt in Metern zurück.

Erforderliche Parameter

  • Abfrage

    Der Textstring, in dem gesucht werden soll. Geben Sie vollständige Wörter und Teilstrings, Ortsnamen, Adressen und Plus Codes an. Über den Autocomplete (New)-Dienst werden mögliche Übereinstimmungen basierend auf dem String zurückgegeben, die nach erkannter Relevanz sortiert werden.

    Rufen Sie zum Festlegen des Abfrageparameters die Methode setQuery() auf, wenn Sie das FindAutocompletePredictionsRequest-Objekt erstellen.

Optionale Parameter

  • Haupttypen

    Eine Liste mit bis zu fünf Ortstypwerten aus den Typen Tabelle A oder Tabelle B, mit denen die in der Antwort zurückgegebenen Orte gefiltert werden. Ein Ort muss mit einem der angegebenen primären Typwerte übereinstimmen, um in die Antwort aufgenommen zu werden.

    Ein Ort kann nur einen primären Typ aus den Typen Tabelle A oder Tabelle B haben, die mit ihm verknüpft sind. 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 werden mehr als fünf Typen angegeben.
    • Alle unbekannten Typen werden angegeben.

    Wenn Sie den Parameter „primary_types“ festlegen möchten, rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setTypesFilter() auf.

  • Länder

    Es werden nur Ergebnisse aus der Liste der angegebenen Länder berücksichtigt. Diese Liste besteht aus bis zu 15 zweistelligen Werten für Ländercodes der Top-Level-Domain (ccTLD). Wenn Sie das Flag weglassen, werden keine Einschränkungen auf die Antwort angewendet. So beschränken Sie die Regionen beispielsweise auf Deutschland und Frankreich:

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

    Wenn Sie den Parameter „countries“ festlegen möchten, rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setCountries() auf.

  • Eingabeversatz

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

    Wenn Sie den Parameter „input_offset“ festlegen möchten, rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setInputOffset() auf.

  • Standortvoreingenommenheit oder Standortbeschränkung

    Sie können eine Standortvorgabe oder eine Standortbeschränkung angeben, aber nicht beides, um den Suchbereich zu definieren. Stellen Sie sich die Standortbeschränkung als Angabe der Region vor, in der sich die Ergebnisse befinden müssen, und die Standortvorgabe als Angabe der Region, in deren Nähe sich die Ergebnisse befinden müssen. Der Hauptunterschied besteht darin, dass bei der Standortvoreingenommenheit auch Ergebnisse außerhalb der angegebenen Region zurückgegeben werden können.

    • Standortverzerrung

      Gibt einen Bereich für die Suche an. Dieser Standort dient als Voreinstellung, nicht als Einschränkung. Daher können auch Ergebnisse außerhalb des angegebenen Bereichs zurückgegeben werden.

      Wenn Sie den Parameter für die Standortvoreingenommenheit festlegen möchten, rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-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.

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

    Geben Sie die Region mit Standortvorgaben oder Standortbeschränkungen 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. Der Standardwert ist 0,0. Bei der Standortbeschränkung muss der Radius einen Wert größer als 0,0 haben. Andernfalls werden keine Ergebnisse zurückgegeben.

    • Ein Rechteck ist ein Breiten-/Längengrad-Darstellungsbereich, der durch zwei diagonal gegenüberliegende Punkte low und high dargestellt wird. Ein Darstellungsbereich gilt als geschlossene Region, d. h., er schließt seine Grenze ein. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen und die Längengradgrenzen zwischen -180 und 180 Grad:

      • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
      • Wenn low.longitude > high.longitude ist, ist der Längengradbereich umgekehrt (der Darstellungsbereich schneidet den Längengrad 180).
      • 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 sein und das Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

  • Ursprung

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

    Wenn Sie den Ursprungsparameter festlegen möchten, rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setOrigin() auf.

  • Regionscode

    Der Regionscode, der zum Formatieren der Antwort verwendet wird, einschließlich der Adressformatierung, angegeben als zweistelliger Wert für die Ländercode der Top-Level-Domain (ccTLD). Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes, wobei es einige Ausnahmen gibt. So lautet beispielsweise die ccTLD des Vereinigten Königreichs „uk“ (.co.uk), der ISO 3166-1-Code dagegen „gb“ (technisch für die Entität „Vereinigtes Königreich von Großbritannien und Nordirland“).

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

    Wenn Sie den Parameter „Regioncode“ festlegen möchten, rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setRegionCode() auf.

  • Sitzungstoken

    Sitzungstokens sind von Nutzern generierte Strings, mit denen Autocomplete-Aufrufe vom Typ „Neu“ als „Sitzungen“ erfasst werden. Bei der automatischen Vervollständigung werden Sitzungstokens verwendet, um die Abfrage- und Auswahlphasen einer Nutzeranfrage zur automatischen Vervollständigung zu Abrechnungszwecken zu einer separaten Sitzung zusammenzufassen. Die Sitzung beginnt, wenn der Nutzer mit der Eingabe beginnt, und endet, wenn er einen Ort auswählt. Jede Sitzung kann mehrere Abfragen und eine Ortsauswahl umfassen. Sobald eine Sitzung beendet wird, 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 zu verwenden, bei denen eine automatische Vervollständigung erfolgt. Wenn Sie ein Fragment einbetten oder die automatische Vervollständigung mithilfe eines Intents starten, übernimmt die API dies automatisch.

    Die automatische Vervollständigung verwendet eine AutocompleteSessionToken, um jede Sitzung zu identifizieren. Ihre App sollte zu Beginn jeder neuen Sitzung ein neues Sitzungstoken übergeben und dann dasselbe Token zusammen mit einer Orts-ID im nachfolgenden Aufruf von fetchPlace() übergeben, um Details zum Ort abzurufen, der vom Nutzer ausgewählt wurde.

    Wenn du den Sitzungstoken-Parameter festlegen möchtest, rufe die Methode setSessionToken() beim Erstellen des FindAutocompletePredictionsRequest-Objekts auf.

    Weitere Informationen finden Sie unter Sitzungstokens.

Beispiele für die automatische Vervollständigung (neu)

Standortbeschränkung und Standortvorgaben verwenden

Bei der automatischen Vervollständigung (neu) wird standardmäßig die IP-Voreingenommenheit verwendet, um den Suchbereich zu steuern. Bei der IP-Voreinnahme verwendet die API die IP-Adresse des Geräts, um die Ergebnisse zu beeinflussen. Sie können optional die Standortbeschränkung oder die Standortvorgabe verwenden, um einen Suchbereich anzugeben. Sie können aber nicht beides gleichzeitig verwenden.

Mit der Standortbeschränkung wird das Gebiet angegeben, in dem gesucht werden soll. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Im folgenden Beispiel wird die Anfrage mithilfe einer Standorteinschränkung auf einen kreisförmigen Bereich mit einem Radius von 5.000 Metern um San Francisco begrenzt:

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 Standortvorgabe dient der Standort 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. Im nächsten Beispiel wird die vorherige Anfrage so geändert, dass die Standortvorlage verwendet wird:

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

Mit dem Parameter primary_types können Sie die Ergebnisse einer Anfrage auf einen bestimmten Typ beschränken, wie in Tabelle A und Tabelle B aufgeführt. Sie können ein Array mit bis zu fünf Werten angeben. Wird dieser Parameter weggelassen, werden alle Typen zurückgegeben.

Im folgenden Beispiel wird der Suchstring „Fußball“ angegeben und die Ergebnisse werden mit dem Parameter „primary_types“ auf Einrichtungen vom Typ "sporting_goods_store" beschränkt:

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 Typs enthalten, den Sie möglicherweise nicht möchten, z. B. "athletic_field".

Ursprung verwenden

Wenn Sie den Parameter origin in die Anfrage aufnehmen, der als Breiten- und Längengrad angegeben ist, enthält die API die Luftlinie vom Startpunkt zum Ziel in der Antwort (Zugriff über getDistanceMeters()). In diesem Beispiel wird der Startpunkt auf 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 (Neu) auch ohne Karte verwenden. Wenn Sie aber eine Karte nutzen, muss es eine Google Maps-Karte sein. Wenn Sie Vorschläge vom Autocomplete (New)-Dienst ohne Karte anzeigen, muss das Google-Logo inline mit dem Suchfeld oder den Suchergebnissen angezeigt werden. Weitere Informationen finden Sie unter Google-Logo und Quellenangaben anzeigen.