Automatische Vervollständigung (neu)

„Autocomplete (New)“ gibt Ortsvorschläge in einer Antwort auf eine Anfrage zurück, die einen Textsuchstring und geografische Grenzen enthält, die den Suchbereich steuern. Die automatische Vervollständigung kann vollständige Wörter und Teilstrings der Eingabe abgleichen und Ortsnamen, Adressen und Pluscodes auflösen. Ihre Anwendung kann Abfragen senden, während der Nutzer tippt, um Vorschläge für Orte und Suchanfragen in Echtzeit zu erhalten.

Angenommen, Sie rufen die Funktion „Autocomplete“ mit einem String auf, der einen Teil der Nutzereingabe „Sicilian piz“ enthält, und begrenzen den Suchbereich auf San Francisco, CA. Die Antwort enthält dann eine Liste von 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.

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

Ihre App kann eine Liste der vorhergesagten Ortsnamen und/oder Adressen von 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());
        })
    );

Automatische Vervollständigung von Antworten (neu)

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

Für jeden vorhergesagten 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 kannst du mit dieser Methode die Abschnitte der Beschreibung, die mit der Suche übereinstimmen, mit CharacterStyle in einem Stil deiner Wahl hervorheben. Der Parameter CharacterStyle ist optional. Legen Sie „null“ fest, wenn keine Hervorhebung erforderlich ist.
• getPrimaryText(CharacterStyle) gibt den Haupttext zurück, der einen Ort beschreibt. Das ist in der Regel 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 beim Anzeigen von Vorschlägen für die automatische Vervollständigung nützlich. Beispiele: Avenue Anatole France, Paris, Frankreich und Sydney, New South Wales.
• getPlaceId() gibt die Orts-ID des vorhergesagten Orts zurück. Eine Orts-ID ist eine Textkennzeichnung, mit der ein Ort eindeutig identifiziert wird. Sie können sie verwenden, um das Place-Objekt später wieder abzurufen. Weitere Informationen zu Orts-IDs in Autocomplete finden Sie unter Place Details (Neu). Allgemeine Informationen zu Orts-IDs finden Sie in der Übersicht über Orts-IDs.
• getTypes() gibt die Liste der Ortstypen zurück, die mit diesem Ort verknüpft sind.
• getDistanceMeters() gibt die Luftlinie in Metern zwischen diesem Ort und dem in der Anfrage angegebenen Startpunkt 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. Der Dienst „Autocomplete (New)“ gibt anhand dieses Strings mögliche Übereinstimmungen zurück und sortiert die Ergebnisse nach ihrer wahrgenommenen Relevanz.

  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 Wertetypen 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. Der primäre Typ kann beispielsweise "mexican_restaurant" oder "steak_house" sein.

  Die Anfrage wird mit dem Fehler INVALID_REQUEST abgelehnt, wenn:

  • Es sind mehr als fünf Typen angegeben.
  • Alle nicht erkannten 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 muss bis zu 15 zweistellige Werte für ccTLDs („Top-Level-Domains“) enthalten. Wird sie weggelassen, 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 Schnittpunkt der beiden Einstellungen.

  Rufen Sie zum Festlegen des Parameters „countries“ die Methode setCountries() auf, wenn Sie das FindAutocompletePredictionsRequest-Objekt erstellen.

• Eingabeoffset

  Der Unicode-Zeichenabstand (ab Null gezählt), der die Cursorposition in der Abfrage angibt. Die Cursorposition kann sich darauf auswirken, welche Vorschläge zurückgegeben werden. Wenn das Feld leer ist, wird standardmäßig die Länge der Abfrage verwendet.

  Rufen Sie zum Festlegen des Eingabeoffset-Parameters die Methode setInputOffset() auf, wenn Sie das FindAutocompletePredictionsRequest-Objekt erstellen.

• Standortabhängige Gewichtung oder Standortbeschränkung

  Sie können entweder eine Standortvorgabe oder eine Standortbeschränkung angeben, um das Suchgebiet zu definieren. Stellen Sie sich die Standorteinschrä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 werden möglicherweise auch Ergebnisse außerhalb des angegebenen Bereichs zurückgegeben.

    Wenn Sie den Parameter für die Standortvoreingenommenheit festlegen möchten, rufen Sie die Methode setLocationBias() auf, wenn Sie das FindAutocompletePredictionsRequest-Objekt erstellen.

  • 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 Standortbeschränkung festlegen möchten, rufen Sie beim Erstellen des FindAutocompletePredictionsRequest-Objekts die Methode setLocationRestriction() auf.

  Geben Sie die Region mit Standortvorgaben oder Standorteinschrä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- und Längengrad-Viewport, der durch zwei diagonal gegenüberliegende Punkte low und high dargestellt wird. Ein Darstellungsbereich gilt als geschlossene Region, d. h., er schließt seine Begrenzung ein. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen und die Längengradgrenzen zwischen -180 und 180 Grad:

    • Wenn low = high, 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, umfasst 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 dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

• Ursprung

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

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

• Regionscode

  Die Regionscode, die zum Formatieren der Antwort verwendet wird, einschließlich der Adressformatierung, angegeben als zweistelliger Wert einer ccTLD („Top-Level-Domain“). Die meisten ccTLD-Codes stimmen mit ISO 3166-1-Codes überein, mit einigen Ausnahmen. 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.

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

• Sitzungstoken

  Sitzungstokens sind von Nutzern generierte Strings, mit denen „Autocomplete (New)“-Aufrufe als „Sitzungen“ erfasst werden. Bei der automatischen Vervollständigung werden Sitzungstokens verwendet, um die Abfrage- und Auswahlphasen einer automatischen Vervollständigung von Suchanfragen zu Abrechnungszwecken in einer einzelnen Sitzung zu gruppieren. Die Sitzung beginnt, wenn der Nutzer beginnt, eine Suchanfrage einzugeben, und endet, wenn er einen Ort auswählt. Jede Sitzung kann mehrere Suchanfragen enthalten, gefolgt von einer Ortsauswahl. 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 Autocomplete-Sitzungen zu verwenden. Wenn Sie ein Fragment einbetten oder Autocomplete mithilfe eines Intents starten, übernimmt die API dies automatisch.

  Für die automatische Vervollständigung wird eine AutocompleteSessionToken verwendet, 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.

  Rufe die Methode setSessionToken() auf, wenn du das FindAutocompletePredictionsRequest-Objekt erstellst, um den Parameter für das Sitzungstoken festzulegen.

  Weitere Informationen finden Sie unter Sitzungstokens.

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

Standortbeschränkungen und Standortvorgaben verwenden

Bei der automatischen Vervollständigung (neu) wird standardmäßig eine 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 verwenden.

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

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 Vorgabe. 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. Wenn Sie diesen Parameter weglassen, 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".

Herkunft verwenden

Wenn Sie den Parameter origin in die Anfrage aufnehmen, der als Koordinaten für Längen- und Breitengrad angegeben ist, enthält die API in der Antwort die Luftlinie vom Startpunkt zum Ziel (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 eine Karte anzeigen, muss es sich um eine Google-Karte handeln. Wenn Sie Vorschläge des Dienstes „Autocomplete (New)“ ohne Karte anzeigen, muss das Google-Logo inline mit dem Suchfeld/den Suchergebnissen angezeigt werden. Weitere Informationen finden Sie unter Google-Logo und Quellenangaben anzeigen.