Automatische Vervollständigung (neu)

„Autocomplete (New)“ gibt Ortsvorschläge als Reaktion auf eine Anfrage zurück, die einen Textsuchstring und geografische Grenzen enthält, mit denen der Suchbereich gesteuert wird. Place Autocomplete 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 der Teilnutzereingabe „Sicilian piz“ als Eingabe auf und beschränken den Suchbereich auf San Francisco, Kalifornien. Die Antwort enthält dann eine Liste mit Ortsvorhersagen, die dem Suchstring und dem Suchgebiet entsprechen, z. B. das Restaurant „Sicilian Pizza Kitchen“. Die zurückgegebenen Ortsvorhersagen sind so konzipiert, dass sie dem Nutzer angezeigt werden, um ihm bei der Auswahl des gewünschten Orts zu helfen. Sie können eine Place Details (New)-Anfrage senden, um weitere Informationen zu den zurückgegebenen Ortsvorhersagen zu erhalten.

Sie haben zwei Möglichkeiten, die Funktion „Autocomplete (New)“ in Ihre App einzubinden:

• Place Autocomplete-Widget hinzufügen: Bietet eine sofort einsatzbereite automatische Vervollständigung der Suche über die Klasse PlaceAutocomplete, die Vorhersagen anzeigt, während der Nutzer tippt.
• Ortsvorhersagen programmatisch abrufen: Rufen Sie die API direkt auf, um Vorhersagen abzurufen und in einer benutzerdefinierten Benutzeroberfläche anzuzeigen.

Das „Place Autocomplete“-Widget hinzufügen

Um die automatische Vervollständigung von Orten einfacher zu gestalten, können Sie das Place Autocomplete-Widget in Ihre App einfügen. Das Widget bietet eine spezielle Vollbildoberfläche, die Nutzereingaben verarbeitet und Ortsvorschläge anzeigt, während AutocompletePrediction-Objekte an die App zurückgegeben werden. Anschließend können Sie eine Place Details (New)-Anfrage senden, um zusätzliche Informationen zu den Ortsvorschlägen zu erhalten.

Wie beim programmatischen Abrufen von Ortsvorhersagen können Sie mit dem Place Autocomplete-Widget Sitzungstokens verwenden, um Autocomplete-Anfragen zu Abrechnungszwecken in Sitzungen zu gruppieren. Sie können ein Sitzungstoken übergeben, wenn Sie die Absicht 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 mit 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:

1. Optional: Sitzungstoken definieren Wenn Sie kein Sitzungstoken angeben, wird eines für Sie erstellt.

2. Definieren Sie einen autocompleteIntent mit den gewünschten Parametern und Ihrem Sitzungstoken.

3. Definieren Sie eine ActivityResultLauncher für StartActivityForResult. Dieser Launcher verarbeitet das Ergebnis, das von der Autocomplete-Aktivität zurückgegeben wird.

4. Verarbeiten Sie das Ergebnis im Callback von ActivityResultLauncher. Dazu müssen Sie die AutocompletePrediction und AutocompleteSessionToken extrahieren (sofern Sie keine eigenen angegeben haben), Fehler beheben und optional eine fetchPlace()-Anfrage senden, um zusätzliche Details zu einem Ort abzurufen.

5. Intent mit placeAutocompleteActivityResultLauncher starten

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

// 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)

// 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, Typografie, Abstände, Ränder und 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 Theme-Ü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>

Anschließend können Sie auf die überschriebenen Stile verweisen, 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);

Ortsvorhersagen programmatisch abrufen

Ihre App kann eine Liste mit vorhergesagten Ortsnamen und/oder Adressen von der Autocomplete API abrufen, indem sie PlacesClient.findAutocompletePredictions() aufruft und ein FindAutocompletePredictionsRequest-Objekt übergibt. Im folgenden Beispiel sehen Sie 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 von Autocomplete (neu)

Die API gibt ein FindAutocompletePredictionsResponse in einem Task zurück. Das FindAutocompletePredictionsResponse-Objekt 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 Anfrage 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 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 einem Stil Ihrer Wahl hervorheben, indem Sie CharacterStyle verwenden. Der Parameter CharacterStyle ist optional. Legen Sie den Wert auf „null“ fest, wenn Sie keine Hervorhebung benötigen.
• getPrimaryText(CharacterStyle) gibt den Haupttext zurück, in dem ein Ort beschrieben wird. Das ist in der Regel der Name des Orts. Beispiele: Eiffelturm und Pitt Street 123.
• getSecondaryText(CharacterStyle) gibt den untergeordneten Text einer Ortsbeschreibung zurück. Dies ist beispielsweise als zweite Zeile nützlich, wenn automatisch vervollständigte Vorhersagen 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 im Antrag angegebenen Ursprung 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. Über den Dienst „Autocomplete (New)“ 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() beim Erstellen des FindAutocompletePredictionsRequest-Objekts auf.

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 einem der angegebenen primären Typwerte entsprechen, damit er in die Antwort aufgenommen wird.

  Ein Ort kann nur einen 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.
  • Es wurden unbekannte Typen angegeben.

  Rufen Sie zum Festlegen des Parameters „primaryTypes“ die Methode setTypesFilter() beim Erstellen des FindAutocompletePredictionsRequest-Objekts auf.

• Länder

  Schließen Sie nur Ergebnisse aus der Liste der angegebenen Länder ein, die als Liste mit bis zu 15 zweistelligen Ländercodes der Top-Level-Domain (ccTLD) angegeben sind. Wenn Sie das Flag weglassen, werden keine Einschränkungen auf die Antwort angewendet. Beispiel: So beschränken Sie die Regionen auf Deutschland und Frankreich:

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

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

• Eingabeversatz

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

  Rufen Sie zum Festlegen des Parameters für den Eingabe-Offset die Methode setInputOffset() beim Erstellen des FindAutocompletePredictionsRequest-Objekts auf.

• Standortabhängige Verzerrung oder Standortbeschränkung

  Sie können eine Standortgewichtung oder eine Standorteinschränkung, aber nicht beides, angeben, um den Suchbereich zu definieren. Bei der Standortbeschränkung wird die Region angegeben, in der sich die Ergebnisse befinden müssen, und beim Standort-Bias die Region, in deren Nähe sich die Ergebnisse befinden müssen. Der Hauptunterschied besteht darin, dass bei der Standortgewichtung weiterhin Ergebnisse außerhalb der angegebenen Region zurückgegeben werden können.

  • Standortbedingte Verzerrung

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

    Wenn Sie den Parameter für die Ortsvoreingenommenheit 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.

    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 für die Standortgewichtung oder ‑beschränkung 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 (jeweils einschließlich). Der Standardwert ist 0,0. Bei einer Standortbeschränkung muss der Radius auf einen Wert größer als 0,0 festgelegt werden. Andernfalls werden keine Ergebnisse zurückgegeben.

  • Ein Rechteck ist ein Sichtbereich, der durch zwei diagonal gegenüberliegende low- und high-Punkte dargestellt wird. Ein Darstellungsbereich gilt als geschlossener Bereich, d. h., er umfasst auch seine Grenze. Die Grenzen für den Breitengrad müssen zwischen -90 und 90 Grad liegen (einschließlich), und die Grenzen für den Längengrad müssen zwischen -180 und 180 Grad liegen (einschließlich):

    • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
    • Wenn low.longitude > high.longitude, wird der Längengradbereich umgekehrt (der Darstellungsbereich überschreitet die 180-Grad-Längengradlinie).
    • Wenn low.longitude = -180 Grad und high.longitude = 180 Grad, 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 Rechteck darf nicht leer sein. Ein leerer Viewport führt zu einem Fehler.

• Ursprung

  Der Ausgangspunkt, von dem aus die Luftlinie zum Ziel berechnet werden soll (über getDistanceMeters() aufgerufen). 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 Ländercode der Top-Level-Domain (ccTLD). Die meisten ccTLD-Codes sind mit den ISO 3166-1-Codes identisch. Es gibt jedoch einige Ausnahmen. Die ccTLD des Vereinigten Königreichs ist beispielsweise „uk“ (.co.uk), der ISO 3166-1-Code „gb“ (technisch für das Land „Vereinigtes Königreich Großbritannien und Nordirland“).

  Wenn Sie einen ungültigen Ländercode angeben, gibt die API einen INVALID_ARGUMENT-Fehler 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 nutzergenerierte Strings, mit denen Autocomplete (New)-Aufrufe – sowohl Aufrufe über das Widget als auch programmatische Aufrufe – 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 App muss für jede Sitzung ein neues Token generieren. Wir empfehlen, Sitzungstokens für alle programmatischen Sitzungen zur automatischen Vervollständigung zu verwenden. Wenn Sie ein Fragment einbetten oder die automatische Vervollständigung über einen Intent 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 dieses Token dann zusammen mit einer Orts-ID im nachfolgenden Aufruf von fetchPlace() übergeben, um Ortsdetails für den vom Nutzer ausgewählten Ort abzurufen.

  Rufen Sie zum Festlegen des Sitzungstokenparameters 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 Standortgewichtung verwenden

Bei der automatischen Vervollständigung (neu) wird standardmäßig die IP-Verschiebung verwendet, um den Suchbereich zu steuern. Bei der IP-Gewichtung verwendet die API die IP-Adresse des Geräts, um die Ergebnisse zu gewichten. Optional können Sie Standortbeschränkung oder Standortbias verwenden, aber nicht beides, um einen Suchbereich anzugeben.

Mit der Standortbeschränkung wird der Bereich angegeben, in dem gesucht werden soll. 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 Metern zu beschränken, die auf San Francisco zentriert ist:

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, auch wenn sie außerhalb des angegebenen Bereichs liegen. Im nächsten Beispiel wird die vorherige Anfrage so geändert, dass der Standort-Bias 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 diese Option nicht angegeben, werden alle Typen zurückgegeben.

Im folgenden Beispiel wird der Suchstring „Soccer“ angegeben und der Parameter „primarytypes“ 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 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 einfügen, angegeben als Breiten- und Längengradkoordinaten, enthält die API die Luftlinie vom Ursprung zum Ziel in der Antwort (über getDistanceMeters()). In diesem Beispiel wird der Ursprung 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

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

Allgemeine Richtlinien:

• Am schnellsten lässt sich eine funktionsfähige Benutzeroberfläche mit dem Autocomplete (New)-Widget der Maps JavaScript API, dem Autocomplete (New)-Widget des Places SDK for Android oder dem Autocomplete (New)-Widget 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 SKU: Autocomplete Request pricing 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.

Benötigt Ihre Anwendung weitere Informationen als Adresse und Breiten-/Längengrad des ausgewählten Vorschlags?

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ändigungen (neu) 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 geben Adressen für untergeordnete Gebäude ein, z. B. Adressen für bestimmte Einheiten oder Wohnungen innerhalb eines Gebäudes. 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 wird Autocomplete (New) angewiesen, vorzugsweise Ergebnisse innerhalb des definierten Bereichs anzuzeigen. Ergebnisse außerhalb dieses Bereichs können aber trotzdem angezeigt werden. Mit dem Parameter components können Sie die Ergebnisse filtern, sodass nur Orte in einem bestimmten Land angezeigt werden.

Standorteinschränkung

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

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