Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

Automatische Vervollständigung (neu)

Plattform auswählen: Android iOS JavaScript Webdienst

Entwickler im Europäischen Wirtschaftsraum (EWR)

Autocomplete (New) gibt Ortsvorhersagen als Antwort auf eine Anfrage zurück, die einen Text Search-String und geografische Grenzen enthält, die den Suchbereich einschränken. Die automatische Vervollständigung findet Übereinstimmungen mit vollständigen Wörtern und Teilstrings der Eingabe, 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.

Sie rufen beispielsweise Autocomplete mit einem String auf, der eine unvollständige Nutzereingabe enthält, z. B. „Sicilian piz“, wobei der Suchbereich auf San Francisco, Kalifornien, beschränkt ist. Die Antwort enthält dann eine Liste mit Ortsvorschlägen, die dem Suchstring und dem Suchbereich entsprechen, z. B. das Restaurant „Sicilian Pizza Kitchen“. Die zurückgegebenen Ortsvorschläge sollen dem Nutzer präsentiert werden, um ihm die Auswahl des gewünschten Orts zu erleichtern. Sie können eine Place Details (New)-Anfrage stellen, um weitere Informationen zu den zurückgegebenen vervollständigten Suchanfragen zu erhalten.

Es gibt zwei Möglichkeiten, die Funktion „Automatische Vervollständigung (Neu)“ in Ihre App einzubinden:

Place Autocomplete-Widget hinzufügen: Mit der Klasse PlaceAutocomplete wird eine sofort einsatzbereite automatische Vervollständigung für die Suche bereitgestellt, die während der Nutzereingabe Vorschläge anzeigt.
Ortsvorschläge programmatisch abrufen: Rufen Sie die API direkt auf, um Vorschläge abzurufen und in einer benutzerdefinierten Benutzeroberfläche anzuzeigen.

Wenn Sie die automatische Vervollständigung von Orten einheitlich gestalten möchten, können Sie das Place Autocomplete-Widget in Ihre App einbinden. Das Widget bietet eine spezielle Vollbildoberfläche, die Nutzereingaben verarbeitet und Ortsvorschläge anzeigt, während AutocompletePrediction-Objekte an die App zurückgegeben werden. Sie können dann eine Place Details (New)-Anfrage stellen, um zusätzliche Informationen zu den Ortsvorschlägen abzurufen.

Wie beim programmatischen Abrufen von Ortsvorschlägen können Sie auch beim Place Autocomplete-Widget Sitzungstokens verwenden, um Autocomplete-Anfragen zu Abrechnungszwecken in Sitzungen zu gruppieren. Sie können ein Sitzungstoken übergeben, wenn Sie den Intent für das Widget erstellen, indem Sie setAutocompleteSessionToken() aufrufen. Wenn Sie kein Sitzungstoken angeben, wird vom Widget eines für Sie erstellt, auf das Sie durch Aufrufen von getSessionTokenFromIntent() zugreifen können. Weitere Informationen zur Verwendung von Sitzungstokens finden Sie unter Sitzungstokens.

So fügen Sie das „Place Autocomplete“-Widget in Ihre App ein:

Optional: Definieren Sie ein Sitzungstoken. Wenn Sie kein Sitzungstoken angeben, wird vom Widget eines für Sie erstellt.
Definieren Sie ein autocompleteIntent mit den gewünschten Parametern und Ihrem Sitzungstoken.
Definieren Sie einen ActivityResultLauncher für StartActivityForResult. Dieser Launcher verarbeitet das von der Autocomplete-Aktivität zurückgegebene Ergebnis.
Verarbeite das Ergebnis im Callback von ActivityResultLauncher. Dazu müssen Sie die AutocompletePrediction und die AutocompleteSessionToken extrahieren (falls Sie keine eigenen angegeben haben), Fehler beheben und optional eine fetchPlace()-Anfrage stellen, um zusätzliche Details zu einem Ort zu erhalten.
Intent mit dem placeAutocompleteActivityResultLauncher starten

In den folgenden Beispielen wird gezeigt, wie Sie das Place Autocomplete-Widget mit Kotlin und Java hinzufügen:

Kotlin

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

Java

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

Design anpassen

Wenn Sie eine Autocomplete-Funktion instanziieren, können Sie ein Design angeben, das alle Standardstilattribute überschreibt. Sie können die Farben, die Typografie, die Abstände, die Rahmen und die Ecken der Place Autocomplete-Komponente anpassen. Die Standardeinstellung ist PlacesMaterialTheme. Für alle Designattribute, die nicht überschrieben werden, werden die Standardstile verwendet.

Sie können Designüberschreibungen in …/res/values/themes.xml definieren. Beispiel:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

Sie können dann die überschriebenen Stile aufrufen, indem Sie setAutocompleteUiCustomization aufrufen:

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

Ortsvorschläge programmatisch abrufen

Ihre App kann eine Liste mit vervollständigten Ortsnamen und/oder Adressen von der Autocomplete API abrufen. Dazu rufen Sie PlacesClient.findAutocompletePredictions() auf und übergeben ein FindAutocompletePredictionsRequest-Objekt. 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());
        })
    );

Hinweis: Weitere Informationen zum Initialisieren von PlacesClient finden Sie unter Places API-Client initialisieren.

Autocomplete (New)-Antworten

Die API gibt ein FindAutocompletePredictionsResponse in einem Task 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 vorhergesagten 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 dem primären und dem sekundären 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 einem Stil Ihrer Wahl hervorheben, indem Sie CharacterStyle verwenden. Der Parameter CharacterStyle ist optional. Setzen Sie den Wert 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 Ortes. Beispiele: „Eiffelturm“ und „123 Pitt Street“.
getSecondaryText(CharacterStyle) gibt den untergeordneten Text einer Ortsbeschreibung zurück. Dies ist beispielsweise als zweite Zeile nützlich, wenn automatische Vervollständigungen angezeigt werden. Beispiele: „Avenue Anatole France, Paris, Frankreich“ und „Sydney, New South Wales“.
getPlaceId() gibt die Orts-ID des vorhergesagten 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 (New). Allgemeine Informationen zu Orts-IDs finden Sie in der Übersicht zur Orts-ID.
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, nach dem gesucht werden soll. Geben Sie vollständige Wörter und Teilstrings, Ortsnamen, Adressen und Plus Codes an. Der Autocomplete-Dienst (New) gibt mögliche Übereinstimmungen basierend auf dem String zurück, die nach erkannter Relevanz sortiert werden.

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

Optionale Parameter

Primäre Typen

Eine Liste mit bis zu fünf Typwerten aus Tabelle A oder Tabelle B, die zum Filtern der in der Antwort zurückgegebenen Orte verwendet werden. Ein Ort muss mit einem der angegebenen primären Typwerte übereinstimmen, damit er in die Antwort aufgenommen wird.

Ein Ort kann nur einen einzigen primären Typ aus Tabelle A oder Tabelle B haben. Der primäre Typ könnte beispielsweise "mexican_restaurant" oder "steak_house" sein.

Die Anfrage wird mit dem Fehler INVALID_REQUEST abgelehnt, wenn:

Es wurden mehr als fünf Typen angegeben.
Sie haben einen unbekannten Typ angegeben.

Wenn Sie den Parameter für primäre Typen 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 kann bis zu 15 Ländercodes der Top-Level-Domain (ccTLD) enthalten. Wenn dieses Feld weggelassen wird, 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.

Eingabe-Offset

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

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

Standortgewichtung oder Standorteinschränkung

Sie können entweder eine Standortgewichtung oder eine Standorteinschränkung angeben, um den Suchbereich zu definieren, aber nicht beides. Bei der Standortbeschränkung wird die Region angegeben, in der sich die Ergebnisse befinden müssen. Bei der Standortgewichtung wird die Region angegeben, in deren Nähe sich die Ergebnisse befinden müssen. Der Hauptunterschied besteht darin, dass bei der Standortgewichtung 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 Gewichtung, nicht als Einschränkung. Es können also auch Ergebnisse außerhalb des angegebenen Bereichs zurückgegeben werden.

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 einen Bereich für die Suche an. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben.

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

Geben Sie die Region für die Standortgewichtung oder 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 liegen (jeweils einschließlich). Der Standardwert ist 0,0. Für die Standorteinschränkung müssen Sie den Radius auf einen Wert größer als 0,0 festlegen. Andernfalls werden keine Ergebnisse zurückgegeben.
Ein Rechteck ist ein Darstellungsbereich mit Breiten- und Längengrad, der durch zwei diagonal gegenüberliegende low- und high-Punkte dargestellt wird. Ein Darstellungsbereich gilt als geschlossene Region, d. h., er schließt seine Grenze ein. Die Grenzen für den Breitengrad müssen zwischen -90 und 90 Grad liegen, die Grenzen für den Längengrad zwischen -180 und 180 Grad:

Hinweis: Die unterstützten Bias-Typen variieren je nach verwendeter SDK-Version. CircularBounds ist nur in Autocomplete (New) verfügbar.
- Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
- Wenn low.longitude > high.longitude, wird der Längengradbereich invertiert (der Darstellungsbereich kreuzt den 180. Längengrad).
- 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 Ausgangspunkt, 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ängengradkoordinaten angegeben werden:

Wenn Sie den Parameter „origin“ 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 der ccTLD („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), der ISO-3166-1-Code dagegen „gb“ (technisch gesehen für das Vereinigte Königreich Großbritannien und Nordirland).

Wenn Sie einen ungültigen Regionscode angeben, gibt die API den Fehler INVALID_ARGUMENT zurück. Der Parameter kann sich je nach anwendbarem Recht auf die Ergebnisse auswirken.

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

Sitzungstoken

Sitzungstokens sind vom Nutzer generierte Strings, mit denen Autocomplete (New)-Aufrufe (sowohl über das Widget als auch programmatisch) 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 wird gestartet, 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 Anwendung 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 mit einem Intent starten, übernimmt die API dies automatisch.

Die automatische Vervollständigung verwendet ein AutocompleteSessionToken, um jede Sitzung zu identifizieren. Ihre App sollte zu Beginn jeder neuen Sitzung ein neues Sitzungstoken übergeben und dieses Token dann zusammen mit einer Orts-ID im nachfolgenden Aufruf von fetchPlace() übergeben, um Place Details für den vom Nutzer ausgewählten Ort abzurufen.

Wenn Sie den Parameter für das Sitzungstoken festlegen möchten, rufen Sie 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 der automatischen Vervollständigung (New) wird standardmäßig die IP-Gewichtung verwendet, um den Suchbereich einzugrenzen. Bei der IP-Gewichtung verwendet die API die IP-Adresse des Geräts, um die Ergebnisse zu gewichten. Sie können optional die Standorteinschränkung oder die Standortgewichtung verwenden, um einen Suchbereich anzugeben, aber nicht beides.

Mit der Standortbeschränkung wird der Suchbereich festgelegt. 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 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 Standortgewichtung 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 Ortsgewichtung 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 weggelassen, werden alle Typen zurückgegeben.

Im folgenden Beispiel wird der Abfragestring „Soccer“ angegeben und der Parameter für primäre Typen 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 „primaryTypes“ weglassen, können die Ergebnisse auch Orte 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 und als Breiten- und Längengradkoordinaten angeben, enthält die 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());
        })
    );

Autocomplete (New)-Optimierung

Hier finden Sie Best Practices, damit Sie den Autocomplete-Dienst (New) optimal nutzen können.

Allgemeine Richtlinien:

Am schnellsten lässt sich eine funktionsfähige Benutzeroberfläche mit dem Widget für die automatische Vervollständigung (neu) der Maps JavaScript API, dem Widget für die automatische Vervollständigung (neu) des Places SDK for Android oder dem Widget für die automatische Vervollständigung (neu) des Places SDK for iOS entwickeln.
Machen Sie sich zu Beginn mit den wichtigsten Datenfeldern von Autocomplete (New) vertraut.
Die Felder zur Standortgewichtung und Standortbeschränkung sind optional, können aber erhebliche Auswirkungen auf die Leistung der automatischen Vervollständigung haben.
Verwenden Sie die Fehlerbehandlung, wenn die API einen Fehler zurückgibt, damit die Anwendung fehlertolerant reagiert.
Die Anwendung sollte Anfragen weiter verarbeiten und weiter funktionieren, auch wenn keine Auswahl getroffen wird.

Best Practices für die Kostenoptimierung

Einfache Kostenoptimierung

Wenn Sie die Kosten für die Nutzung des Autocomplete (New)-Dienstes optimieren möchten, verwenden Sie Feldmasken in Place Details (New)- und Autocomplete (New)-Widgets, damit nur die erforderlichen Datenfelder für Autocomplete (New) zurückgegeben werden.

Erweiterte Kostenoptimierung

Wenn Sie Autocomplete (New) programmatisch implementieren, erhalten Sie Zugriff auf die Preise für die SKU „Autocomplete Request“ und können Geocoding API-Ergebnisse für den ausgewählten Ort anstelle von Place Details (New)-Ergebnissen anfordern. Wenn Sie die Kosten pro Anfrage mit der Geocoding API kombinieren, ist das kosteneffizienter als die Verwendung von Kosten pro Sitzung (sitzungsbasiert), sofern die beiden folgenden Bedingungen erfüllt werden:

Wenn Sie nur den Breiten- und Längengrad oder die Adresse des vom Nutzer ausgewählten Orts abrufen möchten, erhalten Sie entsprechende Informationen über die Geocoding API, für die weniger Kosten anfallen als bei einem Place Details (New)-Aufruf.
Wenn Nutzer eine automatische Vervollständigung bei durchschnittlich maximal 4 entsprechenden Anfragen auswählen, ist der Preis pro Anfrage möglicherweise kosteneffizienter als der Preis pro Sitzung.

Wenn Sie die Autocomplete (New)-Implementierung auswählen möchten, die für Ihre Anwendung am günstigsten ist, suchen Sie in der folgenden Tabelle nach der Zeile, die den Anforderungen Ihrer Anwendung entspricht.

Was in deinem Antrag enthalten sein muss	Durchschnittliche Anzahl der Autocomplete (New)-Anfragen, bevor ein Nutzer einen Vorschlag auswählt	Empfohlene Implementierung
Place Details, die nicht die Adresse und den Standort betreffen, z. B. den Namen des Ortes, den Unternehmensstatus oder die Öffnungszeiten	Beliebig	Sitzungsbasierte Autocomplete (Neu) mit Place Details (Neu)
Nur Adresse und Breiten-/Längengrad des ausgewählten Vorschlags	Vier oder weniger	Anfragebasierte Autocomplete (New) mit der Geocoding API
Nur Adresse und Breiten-/Längengrad des ausgewählten Vorschlags	Mehr als vier	Sitzungsbasierte Autocomplete (New) für Anwendungen, die nur Adressen verwenden

Wenn Sie Autocomplete (New) in Ihrer Anwendung stark nutzen, kann es kostengünstiger sein, anstelle von Place Details (New) die Geocoding API zu verwenden. Die Effizienz der Autovervollständigung (New) jeder Anwendung hängt davon ab, was die Nutzer eingeben, wo die Anwendung verwendet wird und ob die Best Practices zur Leistungsoptimierung implementiert wurden.

Um die durchschnittliche Anzahl der Anfragen für die Tabelle zu ermitteln, analysieren Sie, wie viele Zeichen Nutzer durchschnittlich eingeben, bevor sie in Ihrer Anwendung einen Autocomplete (New)-Vorschlag auswählen.

Sitzungsbasierte Autocomplete-Anfragen (neu) mit Place Details-Anfragen (neu)

Nutzen Sie das sitzungsbasierte Autocomplete (New) mit Place Details (New).
Da Ihre Anwendung Place Details (New) wie den Ortsnamen, den Geschäftsstatus oder die Öffnungszeiten benötigt, sollte Ihre Implementierung von Autocomplete (New) ein Sitzungstoken verwenden (programmatisch oder in die Widgets für JavaScript, Android oder iOS integriert). Die Abrechnung erfolgt pro Sitzung zuzüglich der entsprechenden Places-SKUs, je nachdem, welche Ortsdatenfelder Sie anfordern.¹

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das JavaScript, Android oder iOS integriert. Das umfasst sowohl Autocomplete (New)-Anfragen als auch die Place Details (New)-Anfrage für die ausgewählte Vervollständigung. Der fields-Parameter muss festgelegt werden, damit nur die erforderlichen Autocomplete (New)-Datenfelder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Autocomplete (New)-Anfragen ein Sitzungstoken. Binden Sie die folgenden Parameter ein, wenn Sie Place Details (New) für die ausgewählte Vervollständigung anfordern:

Die Orts-ID aus der Autocomplete (New)-Antwort
Das Sitzungstoken, das in der Autocomplete (New)-Anfrage verwendet wird
Den fields-Parameter, mit dem die erforderlichen Datenfelder für Autocomplete (New) angegeben werden

Automatische Vervollständigung (New) pro Anfrage mit der Geocoding API

Implementieren Sie Autocomplete (New) programmatisch ohne Sitzungstokens und rufen Sie die Geocoding API für die ausgewählte Ortsvervollständigung auf.
Über die Geocoding API erhalten Sie Adressen und Breiten-/Längenkoordinaten. Vier Autocomplete-Anfragen plus ein Geocoding API-Aufruf für die ausgewählte Ortsvervollständigung kosten weniger als eine Sitzung mit Autocomplete (New).¹

Wenn Sie die Best Practices zur Leistung beachten, erhalten Ihre Nutzer bereits mit weniger eingegebenen Zeichen passende Vervollständigungen.

Sitzungsbasierte automatische Vervollständigung (neu) für Anwendungen, die nur Adressen verwenden

Nutzen Sie das sitzungsbasierte Autocomplete (New) mit Place Details (New).
Da die durchschnittliche Anzahl der Anfragen, die Sie voraussichtlich stellen, bevor ein Nutzer eine Autocomplete (New)-Vervollständigung auswählt, die Kosten für die Preisgestaltung pro Sitzung übersteigt, sollte Ihre Implementierung von Autocomplete (New) ein Sitzungstoken sowohl für die Autocomplete (New)-Anfragen als auch für die zugehörige Place Details (New)-Anfrage verwenden. pro Sitzung. ¹

Die Orts-ID aus der Autocomplete (New)-Antwort
Das Sitzungstoken, das in der Autocomplete (New)-Anfrage verwendet wird
Den fields-Parameter, mit dem Felder wie „Adresse“ oder „Geometrie“ angegeben werden

Autocomplete (New)-Anfragen verzögern
Sie können Autocomplete (New)-Anfragen verzögern, bis der Nutzer die ersten 3 oder 4 Zeichen eingegeben hat, damit weniger Anfragen über die Anwendung gestellt werden. Wenn Sie beispielsweise Autocomplete (New)-Anfragen für jedes Zeichen stellen, nachdem der Nutzer das dritte Zeichen eingegeben hat, und der Nutzer sieben Zeichen eingibt und dann eine Vervollständigung auswählt, für die Sie eine Geocoding API-Anfrage stellen, werden die Gesamtkosten für 4 Autocomplete (New)-Anfragen mit Preis pro Anfrage und die Geocoding-Anfrage berechnet.¹

Wenn sich durch das Verzögern von Anfragen Ihre durchschnittliche Anzahl programmatischer Anfragen auf unter 4 senken lässt, empfehlen wir, die Anleitung für eine leistungsstarke Autocomplete (New)-Funktion mit Geocoding API-Implementierung zu beachten. Das Verzögern von Anfragen wird vom Nutzer, der evtl. bei jedem eingegebenen Zeichen mit Vorschlägen rechnet, möglicherweise als Latenz wahrgenommen.

Wenn Sie die Best Practices zur Leistung beachten, erhalten Ihre Nutzer bereits mit weniger eingegebenen Zeichen passende Vervollständigungen.

Informationen zu den Kosten finden Sie in den Preislisten für die Google Maps Platform.

Best Practices für die Leistung

Im Folgenden finden Sie Tipps zum Optimieren der Autocomplete (New)-Leistung:

Binden Sie in Ihre Autocomplete (New)-Implementierung länderspezifische Einschränkungen, eine Standortgewichtung und (bei programmatischen Implementierungen) eine Spracheinstellung ein. Die Spracheinstellung ist bei Widgets nicht erforderlich, weil bei ihnen die Spracheinstellungen aus dem Browser oder vom Mobilgerät des Nutzers übernommen werden.
Wenn Autocomplete (New) mit einer Karte kombiniert wird, können Sie den Standort anhand des Darstellungsbereichs der Karte gewichten.
Wenn ein Nutzer keinen der Vorschläge der automatischen Vervollständigung (New) auswählt, was in der Regel geschieht, wenn es sich bei keinem Vorschlag um die gewünschte Adresse handelt, können Sie anhand der ursprünglichen Nutzereingabe versuchen, relevantere Ergebnisse zu erhalten:
- Wenn der Nutzer voraussichtlich nur Adressinformationen eingibt, können Sie die ursprüngliche Nutzereingabe bei einem Aufruf der Geocoding API noch einmal verwenden.
- Wenn Sie davon ausgehen, dass der Nutzer Abfragen für einen bestimmten Ort mithilfe von Name oder Adresse eingibt, verwenden Sie eine „Place Details (New)“-Anfrage. Wenn nur in einer bestimmten Region Ergebnisse erwartet werden, nutzen Sie die Standortgewichtung.
Bei folgenden Szenarien empfehlen wir, ein Fallback auf die Geocoding API zu nutzen:
- Nutzer, die Adressen von Untereinheiten eingeben, z. B. Adressen für bestimmte Einheiten oder Wohnungen in einem Gebäude. So wird bei der tschechischen Adresse „Stroupežnického 3191/17, Praha“ z. B. eine teilweise Vervollständigung in Autocomplete (New) ausgegeben.
- Wenn Nutzer Adressen mit Präfixen für Straßenabschnitte eingeben, z. B. „23-30 29th St, Queens“ in New York City oder „47-380 Kamehameha Hwy, Kaneohe“ auf der Insel Kauai in Hawaii

Standortgewichtung

Wenn Sie die Parameter location und radius weitergeben, können Sie die Ergebnisse zugunsten eines festgelegten Bereichs gewichten. Dadurch werden von Autocomplete (New) vorzugsweise Ergebnisse für Orte angezeigt, die sich innerhalb des definierten Bereichs befinden. Ergebnisse außerhalb dieses Bereichs können aber trotzdem angezeigt werden. Mit dem Parameter includedRegionCodes können Sie die Ergebnisse so filtern, dass nur Orte in einem bestimmten Land angezeigt werden.

Warnung: Wenn radius nicht angegeben ist, wird der Parameter location ignoriert.

Ergebnisse für Einrichtungen sind im Allgemeinen nicht hoch genug eingestuft, um in den Ergebnissen angezeigt zu werden, wenn der Suchbereich groß ist. Wenn Sie möchten, dass Einrichtungen in gemischten Ergebnissen aus Einrichtungen und Geocodes angezeigt werden, können Sie einen kleineren Radius angeben. Alternativ können Sie types=establishment verwenden, um die Ergebnisse auf Einrichtungen zu beschränken.

Standorteinschränkung

Sie können die Ergebnisse auf einen bestimmten Bereich beschränken, indem Sie den Parameter locationRestriction übergeben.

Sie können die Ergebnisse auch auf die Region beschränken, die durch die Parameter location und radius definiert ist, indem Sie den Parameter locationRestriction hinzufügen. Dadurch wird Autocomplete (New) angewiesen, nur Ergebnisse innerhalb dieser Region zurückzugeben.

Automatische Vervollständigung (neu) Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Das „Place Autocomplete“-Widget hinzufügen

Kotlin

Java

Design anpassen

Ortsvorschläge programmatisch abrufen

Autocomplete (New)-Antworten

Erforderliche Parameter

Abfrage

Optionale Parameter

Primäre Typen

Länder

Eingabe-Offset

Standortgewichtung oder Standorteinschränkung

Standortverzerrung

Standortbeschränkung

Ursprung

Regionscode

Sitzungstoken

Beispiele für Autocomplete (New)

Standortbeschränkung und Standortgewichtung verwenden

Primäre Typen verwenden

Ursprung verwenden

Autocomplete (New)-Optimierung

Best Practices für die Kostenoptimierung

Einfache Kostenoptimierung

Erweiterte Kostenoptimierung

Sitzungsbasierte Autocomplete-Anfragen (neu) mit Place Details-Anfragen (neu)

Automatische Vervollständigung (New) pro Anfrage mit der Geocoding API

Sitzungsbasierte automatische Vervollständigung (neu) für Anwendungen, die nur Adressen verwenden

Best Practices für die Leistung

Standortgewichtung

Standorteinschränkung

Automatische Vervollständigung (neu)