Place Autocomplete

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Plattform auswählen: Android iOS JavaScript Webdienst

Der Autocomplete-Dienst im Places SDK for Android gibt als Antwort auf die Suchanfragen von Nutzern Ortsvorhersagen zurück. Während der Eingabe gibt der Autocomplete-Dienst Vorschläge für Orte wie Unternehmen, Adressen, Plus Codes und POIs aus.

Sie haben die folgenden Möglichkeiten, Ihrer App eine Funktion zur automatischen Vervollständigung hinzuzufügen:

Widget zur automatischen Vervollständigung hinzufügen

Das Autocomplete-Widget ist ein Suchdialogfeld mit integrierter Autocomplete-Funktion. Wenn ein Nutzer Suchbegriffe eingibt, wird im Widget eine Liste mit Vervollständigungen angezeigt, aus denen er auswählen kann. Wenn der Nutzer eine Auswahl trifft, wird eine Place-Instanz zurückgegeben, mit der Ihre App dann Details zum ausgewählten Ort abrufen kann.

Um Ihrer App ein Widget zur automatischen Vervollständigung hinzuzufügen, stehen Ihnen zwei Möglichkeiten zur Verfügung:

Option 1: AutocompleteSupportFragment einbetten

So fügst du deiner App ein AutocompleteSupportFragment hinzu:

  1. Füge dem XML-Layout deiner Aktivität ein Fragment hinzu.
  2. Füge deiner Aktivität oder deinem Fragment einen Listener hinzu.

AutocompleteSupportFragment zu Aktivität hinzufügen

Wenn du AutocompleteSupportFragment einer Aktivität hinzufügen möchtest, füge einem XML-Layout ein neues Fragment hinzu. Beispiel:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • Das Fragment hat standardmäßig keinen Rand und keinen Hintergrund. Verschiebe das Fragment in einem anderen Layoutelement, z. B. mit CardView, um eine einheitliche Darstellung zu ermöglichen.
  • Wenn Sie das Autocomplete-Fragment verwenden und onActivityResult überschreiben müssen, müssen Sie super.onActivityResult aufrufen. Andernfalls funktioniert das Fragment nicht ordnungsgemäß.

PlaceSelectionListener zu Aktivitäten hinzufügen

PlaceSelectionListener verarbeitet die Rückgabe eines Orts als Reaktion auf die Auswahl des Nutzers. Der folgende Code zeigt das Erstellen eines Verweises auf das Fragment und das Hinzufügen eines Listeners zu AutocompleteSupportFragment:

Java


    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
        getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

Kotlin


    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
            as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

Option 2: Intent mit automatischer Vervollständigung starten

Wenn Sie für Ihre App einen anderen Navigationsablauf verwenden möchten, beispielsweise um die automatische Vervollständigung über ein Symbol statt über ein Suchfeld auszulösen, kann Ihre App die automatische Vervollständigung mit einem Intent starten.

Um das Autocomplete-Widget zu starten, gehen Sie wie folgt vor:

  1. Verwenden Sie Autocomplete.IntentBuilder, um einen Intent zu erstellen, und übergeben Sie den gewünschten Autocomplete-Modus. Der Intent muss startActivityForResult aufrufen und einen Anfragecode übergeben, der den Intent identifiziert.
  2. Überschreiben Sie den Callback onActivityResult, um den ausgewählten Ort zu erhalten.

Intent mit automatischer Vervollständigung erstellen

Im folgenden Beispiel wird gezeigt, wie Sie mit Autocomplete.IntentBuilder einen Intent erstellen, um das Autocomplete-Widget als Intent zu starten:

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

Wenn Sie einen Intent zum Starten des Autocomplete-Widgets verwenden, können Sie zwischen Overlay- und Vollbildanzeigemodi wählen. Die folgenden Screenshots zeigen die einzelnen Anzeigemodi:

Im Overlay-Modus wird das Widget für die automatische Vervollständigung über der aufrufenden UI eingeblendet.
Abbildung 1: Autocomplete-Widget im OVERLAY-Modus
Wenn das Widget im Vollbildmodus angezeigt wird, füllt es das gesamte Display aus.
Abbildung 2: Widget für die automatische Vervollständigung im Vollbildmodus

onActivityResult-Callback überschreiben

Wenn Sie eine Benachrichtigung erhalten möchten, sobald der Nutzer einen Ort ausgewählt hat, sollte Ihre App onActivityResult() für die Aktivität überschreiben. Dabei wird auf den Anfragecode geprüft, den Sie wie im folgenden Beispiel für Ihren Intent weitergegeben haben.

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

Ortsvorhersagen programmatisch abrufen

Alternativ zum UI-Widget für die automatische Vervollständigung können Sie eine benutzerdefinierte Such-UI erstellen. Dazu muss Ihre Anwendung Ortsvorhersagen programmatisch abrufen. Ihre App kann eine Liste mit vorhergesagten Ortsnamen und/oder Adressen aus der Autocomplete API abrufen, indem Sie PlacesClient.findAutocompletePredictions() aufrufen und ein FindAutocompletePredictionsRequest-Objekt mit den folgenden Parametern übergeben:

  • Erforderlich:Ein query-String mit dem vom Nutzer eingegebenen Text.
  • Empfohlen: AutocompleteSessionToken, in dem die Abfrage- und Auswahlphasen einer Nutzersuche zu Abrechnungszwecken in eine separate Sitzung gruppiert werden. Die Sitzung beginnt, wenn der Nutzer beginnt, eine Suchanfrage einzugeben, und endet, wenn er einen Ort auswählt.
  • Empfohlen:Ein RectangularBounds-Objekt, das Breiten- und Längengradgrenzen angibt, um Ergebnisse auf die angegebene Region zu beschränken.
  • Optional:Ein oder mehrere zweistellige Ländercodes (ISO 3166-1 Alpha-2) mit den Ländern, auf die Ergebnisse beschränkt werden sollen.
  • Optional: TypeFilter, mit dem Sie die Ergebnisse auf den angegebenen Ortstyp einschränken können. Die folgenden Ortstypen werden unterstützt:

    • TypeFilter.GEOCODE: Gibt nur Geocoding-Ergebnisse und keine Unternehmen zurück. Verwenden Sie diese Anfrage, um die Ergebnisse eindeutig zu machen, wenn der angegebene Standort unbestimmt sein kann.
    • TypeFilter.ADDRESS: Gibt nur automatisch vervollständigte Ergebnisse mit einer genauen Adresse zurück. Verwenden Sie diesen Typ, wenn Sie wissen, dass der Nutzer nach einer vollständig angegebenen Adresse sucht.
    • TypeFilter.ESTABLISHMENT: Gibt nur Orte zurück, die von Unternehmen sind.
    • TypeFilter.REGIONS: Gibt nur Orte zurück, die einem der folgenden Typen entsprechen:

      • LOCALITY
      • SUBLOCALITY
      • POSTAL_CODE
      • COUNTRY
      • ADMINISTRATIVE_AREA_LEVEL_1
      • ADMINISTRATIVE_AREA_LEVEL_2
    • TypeFilter.CITIES: Gibt nur Ergebnisse zurück, die mit LOCALITY oder ADMINISTRATIVE_AREA_LEVEL_3 übereinstimmen.

  • Optional:LatLng, der den Ursprung der Anfrage angibt. Wenn Sie setOrigin() aufrufen, gibt der Dienst für jede automatisch vervollständigte Vorhersage in der Antwort die Entfernung in Metern (distanceMeters) vom angegebenen Ursprung zurück.

Informationen zu Ortstypen finden Sie in der Anleitung zu Ortstypen.

Das folgende Beispiel zeigt einen vollständigen Aufruf von PlacesClient.findAutocompletePredictions().

Java


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
        // Call either setLocationBias() OR setLocationRestriction().
        .setLocationBias(bounds)
        //.setLocationRestriction(bounds)
        .setOrigin(new LatLng(-33.8749937,151.2041382))
        .setCountries("AU", "NZ")
        .setTypeFilter(TypeFilter.ADDRESS)
        .setSessionToken(token)
        .setQuery(query)
        .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

Kotlin


    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypeFilter(TypeFilter.ADDRESS)
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: " + exception.statusCode)
            }
        }

      

Die API gibt einen FindAutocompletePredictionsResponse in einem Task zurück. Die FindAutocompletePredictionsResponse enthält eine Liste von AutocompletePrediction-Objekten, die die vorhergesagten Orte darstellen. Die Liste ist möglicherweise leer, 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 primärem und sekundärem Text. Beispiel: Eiffelturm, Avenue Anatole Frankreich, Paris, Frankreich" Außerdem können Sie mit dieser Methode mithilfe von CharacterStyle die Abschnitte der Beschreibung markieren, die der Suche mit dem Stil Ihrer Wahl entsprechen. Der Parameter CharacterStyle ist optional. Setzen Sie sie auf null, wenn Sie keine Hervorhebung benötigen.
  • getPrimaryText(CharacterStyle) gibt den Haupttext zurück, der einen Ort beschreibt. In der Regel ist dies der Name des Orts. Beispiele: Eiffelturm und Kastanienallee 123.
  • getSecondaryText(CharacterStyle) gibt den Text einer Substanz eines Orts zurück. Dies ist beispielsweise in einer zweiten Zeile nützlich, wenn Vervollständigungen angezeigt werden. Beispiele: Avenue Anatole France, Paris, France"Sydney, New South Wales"
  • getPlaceId() gibt die Orts-ID des vorhergesagten Orts zurück. Eine Orts-ID ist eine ID in Textform, die einen Ort eindeutig bezeichnet und zum späteren Abrufen des Place-Objekts verwendet werden kann. Weitere Informationen zu Orts-IDs im Places SDK for Android finden Sie unter Place Details. Allgemeine Informationen zu Orts-IDs finden Sie unter Orts-ID.
  • getPlaceTypes() gibt die Liste der mit diesem Ort verknüpften Ortstypen zurück.
  • getDistanceMeters() gibt die direkte Linie in Metern zwischen diesem Ort und dem in der Anfrage angegebenen Ursprung zurück.

Sitzungstokens

Sitzungstoken gruppieren die Abfrage- und Auswahlphasen einer automatischen Vervollständigung der Suche zu Abrechnungszwecken in eine separate Sitzung. Die Sitzung beginnt, wenn der Nutzer beginnt, eine Suchanfrage einzugeben, und endet, wenn er einen Ort auswählt. Jede Sitzung kann mehrere Abfragen enthalten, gefolgt von einer Ortsauswahl. Nach Beendigung einer Sitzung ist das Token nicht mehr gültig. Ihre Anwendung muss für jede Sitzung ein neues Token generieren. Wir empfehlen, für alle programmatischen Sitzungen mit automatischer Vervollständigung Sitzungs-Tokens zu verwenden. Wenn Sie ein Fragment einbetten oder die automatische Vervollständigung mit einem Intent starten, übernimmt die API dies automatisch.

Das Places SDK for Android verwendet eine AutocompleteSessionToken, um jede Sitzung zu identifizieren. Ihre App sollte zu Beginn jeder neuen Sitzung ein neues Sitzungstoken übergeben und dieses Token zusammen mit einer Orts-ID im nachfolgenden Aufruf von fetchPlace() übergeben, um Ortsdetails für den vom Nutzer ausgewählten Ort abzurufen.

Weitere Informationen zu Sitzungstokens

Ergebnisse der automatischen Vervollständigung einschränken

Sie können die Ergebnisse der automatischen Vervollständigung auf eine bestimmte geografische Region beschränken und/oder die Ergebnisse auf einen oder mehrere Ortstypen oder bis zu fünf Länder filtern. Sie können diese Einschränkungen auf die Autocomplete-Aktivität, AutocompleteSupportFragment und die programmatische Autocomplete-API anwenden.

So schränken Sie die Ergebnisse ein:

  • Um Ergebnisse innerhalb der definierten Region bevorzugt zu haben, rufen Sie setLocationBias() auf. Einige Ergebnisse außerhalb der definierten Region können weiterhin zurückgegeben werden.
  • Um nur Ergebnisse innerhalb der definierten Region anzuzeigen, rufen Sie setLocationRestriction() auf. Es werden nur Ergebnisse innerhalb der definierten Region zurückgegeben.
  • Um nur Ergebnisse zurückzugeben, die einem bestimmten Ortstyp entsprechen, rufen Sie setTypeFilter() auf. Wenn Sie beispielsweise TypeFilter.ADDRESS angeben, werden nur Ergebnisse mit einer genauen Adresse zurückgegeben.
  • Rufen Sie setCountries() auf, um nur Ergebnisse innerhalb von bis zu fünf angegebenen Ländern zurückzugeben. Länder müssen als zweistelliger Ländercode gemäß ISO 3166-1 Alpha-2 übergeben werden.

Ergebnisse auf eine bestimmte Region gewichten

Rufen Sie setLocationBias() auf und übergeben Sie RectangularBounds, um die automatische Vervollständigung auf eine bestimmte geografische Region zu beschränken. Das folgende Codebeispiel zeigt, wie setLocationBias() für eine Fragmentinstanz aufgerufen wird, um die Vorschläge für die automatische Vervollständigung auf eine Region von Sydney (Australien) auszurichten.

Java


    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

      

Kotlin


    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Ergebnisse auf eine bestimmte Region beschränken

Um die Ergebnisse der automatischen Vervollständigung auf eine bestimmte geografische Region zu beschränken, rufen Sie setLocationRestriction() auf und übergeben Sie einen RectangularBounds. Das folgende Codebeispiel zeigt, wie setLocationRestriction() für eine Fragmentinstanz aufgerufen wird, um die automatisch vervollständigten Vorschläge auf eine Region von Sydney (Australien) auszurichten.

Java


    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

      

Kotlin


    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

Hinweis:Diese Einschränkung gilt nur für vollständige Routen. Synthetische Ergebnisse, die sich außerhalb der rechteckigen Begrenzungen befinden, können basierend auf einer Route zurückgegeben werden, die sich mit der Standortbeschränkung überschneidet.

Ergebnisse nach Ortstyp filtern

Sie können Ergebnisse aus einer Autocomplete-Anfrage so einschränken, dass sie nur einen bestimmten Ortstyp zurückgeben. Wenn die Ergebnisse nicht eingeschränkt sind, werden alle Typen zurückgegeben. Im Allgemeinen ist nur ein Typ zulässig. Die Ausnahme ist, dass Sie die Typen GEOCODE und ESTABLISHMENT sicher mischen können. Dies hat jedoch denselben Effekt, wenn keine Typen angegeben werden.

Um Ergebnisse der automatischen Vervollständigung nach einem bestimmten Ortstyp zu filtern, rufen Sie setTypeFilter() auf, um den zu verwendenden Filter festzulegen. Übergeben Sie anschließend den Filter an ein Fragment oder einen Intent.

Das folgende Codebeispiel zeigt, wie setTypeFilter() für ein AutocompleteSupportFragment aufgerufen wird, um einen Filter festzulegen, der nur Ergebnisse mit einer genauen Adresse zurückgibt.

Java


    autocompleteFragment.setTypeFilter(TypeFilter.ADDRESS);

      

Kotlin


    autocompleteFragment.setTypeFilter(TypeFilter.ADDRESS)

      

Das folgende Codebeispiel zeigt, wie setTypeFilter() bei einem IntentBuilder aufgerufen wird, um einen Filter festzulegen, der nur Ergebnisse mit einer genauen Adresse zurückgibt.

Java


    Intent intent = new Autocomplete.IntentBuilder(
        AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypeFilter(TypeFilter.ADDRESS)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypeFilter(TypeFilter.ADDRESS)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

Informationen zu Ortstypen finden Sie in der Anleitung zu Ortstypen.

Ergebnisse nach Land filtern

Um die Ergebnisse der automatischen Vervollständigung zu filtern, rufen Sie setCountries() auf und legen Sie den Ländercode fest. Übergeben Sie anschließend den Filter an ein Fragment oder einen Intent. Länder müssen als zweistelliger Ländercode gemäß ISO 3166-1 Alpha-2 übergeben werden.

Das folgende Codebeispiel zeigt, wie setCountries() für ein AutocompleteSupportFragment aufgerufen wird, um einen Filter festzulegen, der nur Ergebnisse innerhalb der angegebenen Länder zurückgibt.

Java


    autocompleteFragment.setCountries("AU", "NZ");

      

Kotlin


    autocompleteFragment.setCountries("AU", "NZ")

      

Nutzungslimits

Die Nutzung der Places API, einschließlich des Places SDK for Android, ist nicht mehr auf eine bestimmte Anzahl von Anfragen pro Tag beschränkt. Die folgenden Nutzungslimits gelten jedoch weiterhin:

  • Die Ratenbegrenzung beträgt 100 Anfragen pro Sekunde (Abfragen pro Sekunde). Sie wird als Summe der clientseitigen und serverseitigen Anfragen für alle Anwendungen berechnet, die die Anmeldedaten desselben Projekts verwenden.

Zuordnungen in der App anzeigen

  • Wenn Ihre App den Dienst für die automatische Vervollständigung programmatisch verwendet, muss Ihre UI entweder eine Quellenangabe von Google oder auf einer Karte mit Google-Logo enthalten.
  • Wenn Ihre App das Widget für die automatische Vervollständigung verwendet, müssen Sie nichts weiter tun. Die erforderliche Attribution wird standardmäßig angezeigt.
  • Wenn Sie nach dem Abrufen eines Orts nach ID zusätzliche Ortsinformationen abrufen und anzeigen, müssen Sie auch Quellenangaben von Drittanbietern angeben.

Weitere Informationen finden Sie in der Dokumentation zu Attributionen.

Place Autocomplete-Optimierung

In diesem Abschnitt werden Best Practices beschrieben, mit denen Sie den Place Autocomplete-Dienst optimal nutzen können.

Einige allgemeine Richtlinien:

  • Am schnellsten lässt sich eine funktionierende Benutzeroberfläche mit dem Widget „Autocomplete“ der Maps JavaScript API, dem Widget „Autocomplete“ des Places SDK for Android oder dem Widget „Autocomplete UI“ für das iOS SDK für iOS entwickeln.
  • Machen Sie sich von Anfang an mit den wichtigsten Datenfeldern von Place Autocomplete 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, um sicherzustellen, dass sich die Fehlertoleranz der Anwendung beeinträchtigt, wenn die API einen Fehler zurückgibt.
  • Achte darauf, dass deine App auch dann verarbeitet wird, wenn keine Auswahl getroffen wird und Nutzern die Möglichkeit geboten wird, fortzufahren.

Best Practices für die Kostenoptimierung

Grundlegende Kostenoptimierung

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

Erweiterte Kostenoptimierung

Ziehen Sie die programmatische Implementierung von Place Autocomplete in Betracht, um auf Preise pro Anfrage zuzugreifen und Geocoding API-Ergebnisse für den ausgewählten Ort anstelle von Place Details anzufordern. Die Preise pro Anfrage in Kombination mit der Geocoding API sind kostengünstiger als Preise pro Sitzung (sitzungsbasiert), wenn die beiden folgenden Bedingungen erfüllt sind:

  • Wenn Sie nur den Breiten-/Längengrad oder die Adresse des ausgewählten Orts benötigen, liefert die Geocoding API diese Informationen für einen „Place Details“-Aufruf.
  • Wenn Nutzer eine automatische Vervollständigung bei durchschnittlich vier Suchanfragen auswählen, sind die Preise pro Anfrage möglicherweise kosteneffizienter als die Preise pro Sitzung.
Wenn Sie Hilfe bei der Auswahl der Place Autocomplete-Implementierung benötigen, wählen Sie den Tab aus, der Ihrer Antwort auf die folgende Frage entspricht.

Sind für Ihre Anwendung andere Informationen als die Adresse und der Breiten-/Längengrad der ausgewählten Vervollständigung erforderlich?

Ja, weitere Details erforderlich

Verwenden Sie die sitzungsbasierte Place Autocomplete-Funktion mit Place Details-Anfragen.
Da für Ihre Anwendung Ortsdetails wie der Name des Orts, der Geschäftsstatus oder die Öffnungszeiten erforderlich sind, sollte bei der Implementierung von Place Autocomplete ein Sitzungstoken (programmatisch oder in die Widgets JavaScript, Android oder iOS) integriert sein.Die Gesamtkosten betragen 0,017 $pro Sitzung und die anwendbaren Places-Daten-SKUs, je nachdem, welche Ortsdatenfelder angefordert werden.

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in die Widgets
JavaScript, Android oder iOS integriert. Dies umfasst sowohl die Place Autocomplete-Anfragen als auch die Place Details-Anfrage für die ausgewählte Vervollständigung. Gib unbedingt den Parameter fields an, damit nur die erforderlichen Datenfelder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Ihre Place Autocomplete-Anfragen ein Sitzungstoken. Geben Sie die folgenden Parameter an, wenn Sie Place Details zur ausgewählten Vervollständigung anfordern:

  1. Die Place ID aus der Place Autocomplete-Antwort
  2. Das Sitzungstoken, das in der Place Autocomplete-Anfrage verwendet wird
  3. Der Parameter fields, der die erforderlichen Ortsdatenfelder angibt

Nein, es sind nur Adresse und Standort erforderlich

Die Geocoding API kann für Ihre Anwendung eine kostengünstigere Option als die „Place Details“-Funktion sein, abhängig von der Leistung Ihrer Place Autocomplete-Nutzung. Die Effizienz der automatischen Vervollständigung von Anwendungen hängt davon ab, was Nutzer eingeben, wo sie verwendet werden und ob Best Practices für die Leistungsoptimierung implementiert wurden.

Um die folgende Frage zu beantworten, analysieren Sie, wie viele Zeichen ein Nutzer durchschnittlich eingibt, bevor Sie in Ihrer App eine Place Autocomplete-Vervollständigung auswählen.

Wählen Ihre Nutzer durchschnittlich vier oder weniger Anfragen für die automatische Vervollständigung von Orten aus?

Ja

Place Autocomplete programmatisch ohne Sitzungstoken implementieren und die Geocoding API für die ausgewählte Ortsvorhersage aufrufen.
Die Geocoding API liefert Adressen und Breiten-/Längenkoordinaten für 0,005 $pro Anfrage. Vier Place Autocomplete – Per Request-Anfragen kosten 0,01132 $. Die Gesamtkosten für vier Anfragen sowie ein Geocoding API-Aufruf für die ausgewählte Ortsvorhersage wären dann 0,01632 $. Dieser Wert liegt unter dem Preis für die automatische Vervollständigung von Sitzungen von 0,017 $pro Sitzung.1

Mithilfe von Best Practices zur Leistung können Sie Nutzern helfen, Vorhersagen zu treffen, die sie mit weniger Zeichen erfüllen.

Nein

Verwenden Sie die sitzungsbasierte Place Autocomplete-Funktion mit Place Details-Anfragen.
Da die durchschnittliche Anzahl von Anfragen, die Sie erwarten, bevor ein Nutzer eine Place Autocomplete-Vorhersage auswählt, die Kosten pro Sitzung übersteigt, sollte Ihre Implementierung von Place Autocomplete für die Place Autocomplete-Anfragen und die zugehörige Place Details-Anfrage jeweils ein Sitzungstoken von insgesamt 0,017 $pro Sitzung verwenden.1

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in die Widgets JavaScript, Android oder iOS integriert. Dies umfasst sowohl die Place Autocomplete-Anfragen als auch die Place Details-Anfrage für die ausgewählte Vervollständigung. Geben Sie unbedingt den Parameter fields an, damit nur Basisdaten-Felder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Ihre Place Autocomplete-Anfragen ein Sitzungstoken. Geben Sie die folgenden Parameter an, wenn Sie Place Details zur ausgewählten Vervollständigung anfordern:

  1. Die Place ID aus der Place Autocomplete-Antwort
  2. Das Sitzungstoken, das in der Place Autocomplete-Anfrage verwendet wird
  3. Der Parameter fields, der Basisdaten-Felder wie Adresse und Geometrie angibt

Verzögern Sie Place Autocomplete-Anfragen.
Sie können beispielsweise eine Place Autocomplete-Anfrage verzögern, bis der Nutzer die ersten drei oder vier Zeichen eingegeben hat, sodass Ihre App weniger Anfragen stellt. Wenn beispielsweise Place Autocomplete-Anfragen für jedes Zeichen erfolgen, nachdem der Nutzer das dritte Zeichen eingegeben hat, würden die Gesamtkosten pro Nutzer, der sieben Zeichen eingibt und für die Sie eine Geocoding API-Anfrage stellen, 0,01632 $betragen (4 x 0,00283 $ für die automatische Vervollständigung pro Anfrage + 0,005 $für Geocoding).1

Wenn Ihre durchschnittliche programmatische Anfrage bei Anfragen unter drei liegen kann, folgen Sie der Anleitung für die leistungsstarke Place Autocomplete-Funktion mit der Geocoding API. Beachten Sie, dass die Verzögerung von Anfragen vom Nutzer, der möglicherweise mit jedem neuen Tastenanschlag Vorhersagen erwartet, als Latenz wahrgenommen wird.

Mithilfe von Best Practices zur Leistung können Sie Nutzern helfen, die Vorhersage zu erhalten, nach der sie suchen.


  1. Die hier aufgeführten Kosten sind in US-Dollar angegeben. Die vollständigen Preise finden Sie auf der Seite Google Maps Platform – Abrechnung.

Best Practices für die Leistung

In den folgenden Richtlinien wird beschrieben, wie die Leistung von Place Autocomplete optimiert werden kann:

  • Fügen Sie Ihrer Place Autocomplete-Implementierung länderspezifische Einschränkungen, die Standortverzerrung und (bei programmatischen Implementierungen) die Spracheinstellung hinzu. Die Spracheinstellung ist bei Widgets nicht erforderlich, da sie Spracheinstellungen vom Browser oder Mobilgerät des Nutzers auswählen.
  • Wenn die Place Autocomplete-Funktion von einer Karte begleitet wird, können Sie den Standort anhand des Darstellungsbereichs der Karte anpassen.
  • Wenn ein Nutzer keine der automatischen Vervollständigungen auswählt, denn in der Regel handelt es sich dabei nicht um die gewünschte Ergebnisadresse. In diesem Fall kannst du die ursprüngliche Nutzereingabe wiederverwenden, um relevantere Ergebnisse zu erhalten:
    • Wenn der Nutzer nur Adressinformationen eingeben soll, verwenden Sie die ursprüngliche Nutzereingabe bei einem Aufruf der Geocoding API noch einmal.
    • Wenn du davon ausgehst, dass der Nutzer Abfragen für einen bestimmten Ort nach Name oder Adresse eingibt, verwende eine Find Place-Anfrage. Wenn Ergebnisse nur in einer bestimmten Region erwartet werden, verwenden Sie die Standortgewichtung.
    Wenn Sie zur Geocoding API zurückkehren möchten, sind weitere Szenarien möglich:
    • Nutzer, die untergeordnete Adressen in anderen Ländern als Australien, Neuseeland oder Kanada eingeben. Beispielsweise wird die US-Adresse 123 Bowdoin St #456, Boston MA, USA nicht von der automatischen Vervollständigung unterstützt. (Die automatische Vervollständigung unterstützt nur lokale Adressen in Australien, Neuseeland und Kanada. Unterstützte Adressformate in diesen drei Ländern sind &9
    • Nutzer, die Adressen mit Präfixen für Straßensegmente wie „23-30 29th St, Queens & New York City“ oder „47–380 Kamphameha Hwy, Kaneohe“ auf der Insel Kauai in Hawaii eingeben

Fehlerbehebung

Obwohl viele verschiedene Fehler auftreten können, werden die meisten Fehler, die in der Anwendung wahrscheinlich auftreten, in der Regel durch Konfigurationsfehler (z. B. Verwendung des falschen API-Schlüssels oder fehlerhafter API-Schlüssel) oder Kontingentfehler (Ihre App hat das Kontingent überschritten) verursacht. Weitere Informationen zu Kontingenten finden Sie unter Nutzungslimits.

Fehler, die bei der Verwendung der Steuerelemente für die automatische Vervollständigung auftreten, werden im Callback onActivityResult() zurückgegeben. Rufen Sie Autocomplete.getStatus() auf, um die Statusmeldung für das Ergebnis abzurufen.