Automatische Vervollständigung (neu)

Plattform auswählen: Android iOS JavaScript Webdienst

„Autocomplete (New)“ gibt Ortsvorschläge in Antwort auf eine Anfrage zurück, die einen Textsuchstring und geografische Grenzen enthält, die den Suchbereich steuern. Automatische Vervollständigung kann übereinstimmen auf vollständige Wörter und Teilzeichenfolgen der Eingabe, die Auflösung von Ortsnamen, Adressen und Plus Codes. Ihre Anwendung kann Abfragen senden während der Nutzer tippt, um spontan Vorschläge für Orte und Suchanfragen bereitzustellen.

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

Die zurückgegebenen Ortsvorschläge sind so konzipiert, dass sie dem Nutzer angezeigt werden, um Ihnen zu helfen, den gewünschten Ort auswählen. Sie können Place Details (Neu) Anforderung, mehr zu erhalten Informationen zu allen zurückgegebenen Ortsvorschlägen

Hinweis: „Autocomplete (New)“ ist im Places SDK für Android-Version 3.5.0 und höher verfügbar. Weitere Informationen finden Sie unter SDK auswählen Weitere Informationen zur Verwendung der in Version 4.0.0 hinzugefügten Kotlin APIs finden Sie in der Referenzübersicht.

Autocomplete (New)-Anfragen

Ihre App kann eine Liste der vorgeschlagenen Ortsnamen und/oder Adressen aus der Autocomplete API abrufen, indem Sie PlacesClient.findAutocompletePredictions() aufrufen und ein FindAutocompletePredictionsRequest-Objekt übergeben. Das folgende Beispiel zeigt einen vollständigen Aufruf von PlacesClient.findAutocompletePredictions().

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Hinweis: Aufrufe mit Place Autocomplete-Widgets werden immer an Place Autocomplete und nicht an Place Autocomplete (New) gesendet. Widgetaufrufe sind von der Initialisierungsmethode nicht betroffen.

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

Mit einem CancellationToken können Sie versuchen, eine Anfrage an eine der Anfrageklassen (z. B. FetchPlaceRequest) abzubrechen. Die Stornierung erfolgt auf Best-Effort-Basis. Nachdem eine Kündigungsanfrage gestellt wurde, wird keine Antwort mehr zurückgegeben. Das Ausstellen eines Kündigungstokens garantiert NICHT, dass eine bestimmte Anfrage wird storniert. Ihnen wird die Anfrage auch dann in Rechnung gestellt, wenn keine Antwort zurückgegeben.

Autocomplete (New) – Antworten

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

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

• getFullText(CharacterStyle) 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, France. Außerdem können Sie mit dieser Methode die Abschnitte der die der Suchanfrage einem Stil Ihrer Wahl entsprechen. CharacterStyle Der Parameter CharacterStyle ist optional. Legen Sie den Wert auf „null“ fest, wenn keine Hervorhebung erforderlich ist.
• getPrimaryText(CharacterStyle) gibt den Haupttext zurück, in dem ein Ort beschrieben wird. Dies ist normalerweise der Name des Beispiele: Eiffelturm und 123 Pitt Street.
• getSecondaryText(CharacterStyle) gibt den Zusatztext einer Ortsbeschreibung zurück. Das ist beispielsweise als zweite Zeile bei der Anzeige von automatischen Vervollständigungsvorschlägen nützlich. Beispiele: Avenue Anatole France, Paris, France und Sydney, New South Wales.
• getPlaceId() gibt die Orts-ID des vorhergesagten Orts zurück. Eine Orts-ID ist ein Text- Kennung zur eindeutigen Identifizierung eines Ortes, die Sie verwenden können, um die Place -Objekt zu erstellen. Weitere Informationen zu Orts-IDs in Autocomplete finden Sie unter Place Details (neu). Allgemeine Informationen zu Orts-IDs finden Sie in der Übersicht zu Orts-IDs.
• getTypes() gibt die Liste der mit diesem Ort verknüpften Ortstypen zurück.
• getDistanceMeters() gibt die Luftlinie zwischen diesem Ort und dem in der Anfrage angegebenen Startpunkt in Metern zurück.

Erforderliche Parameter

• Abfrage

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

  Rufen Sie zum Festlegen des Abfrageparameters die Methode setQuery() auf. beim Erstellen des FindAutocompletePredictionsRequest-Objekts.

Optionale Parameter

• Haupttypen

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

  Ein Ort kann nur einen primären Typ aus den Typen Tabelle A oder Tabelle B haben, die mit ihm verknüpft sind. Der primäre Typ kann beispielsweise "mexican_restaurant" oder "steak_house".

  In folgenden Fällen wird die Anfrage mit dem Fehler INVALID_REQUEST abgelehnt:

  • Es werden mehr als fünf Typen angegeben.
  • Alle unbekannten Typen werden angegeben.

  Rufen Sie zum Festlegen des primären Typenparameters die Methode setTypesFilter() auf. beim Erstellen des FindAutocompletePredictionsRequest-Objekts.

• Länder

  Nur Ergebnisse aus der Liste bestimmter Länder einschließen (eine Liste von bis zu 15 Ländern) ccTLD („Top-Level-Domain“) aus zwei Zeichen bestehen. Wenn keine Angabe gemacht 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.

  Rufen Sie zum Festlegen des Länderparameters die Methode setCountries() auf. beim Erstellen des FindAutocompletePredictionsRequest-Objekts.

• Eingabeversatz

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

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

• Standortvoreingenommenheit oder Standortbeschränkung

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

  • Standortverzerrung

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

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

  • 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. beim Erstellen des FindAutocompletePredictionsRequest-Objekts.

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

    Hinweis: Die unterstützten Voreingenommenheitstypen variieren je nach verwendeter SDK-Version. CircularBounds ist nur in der automatischen Vervollständigung (neu) verfügbar.
    • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
    • Wenn low.longitude > high.longitude, der Längengradbereich ist invertiert (der Darstellungsbereich überschreitet die 180-Grad-Längenlinie).
    • Wenn low.longitude = -180 Grad und high.longitude = 180 Grad ist, enthält der Darstellungsbereich alle Längengrade.
    • Wenn low.longitude = 180 Grad und high.longitude = -180 Grad ist, ist der Längengradbereich leer.

    Sowohl low als auch high müssen ausgefüllt werden und das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

• Ursprung

  Der Ursprungspunkt, von dem aus die direkte Entfernung zum Ziel (Zugriff über getDistanceMeters()) Wenn dieser Wert gleich ausgelassen, wird keine geradlinige Entfernung zurückgegeben. Muss angegeben werden als Längen- und Breitengrade:

  Rufen Sie zum Festlegen des Parameters „origin“ den setOrigin() auf. beim Erstellen des FindAutocompletePredictionsRequest-Objekts.

• Regionscode

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

  Hinweis: Der Regionscode soll die Region angeben, aus der die Anfrage stammt, nicht unbedingt die Zielregion für die Abfrage.

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

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

• Sitzungstoken

  Sitzungstokens sind vom Nutzer erstellte Strings, Autocomplete (New)-Aufrufe werden als „Sitzungen“ bezeichnet. Bei der automatischen Vervollständigung werden Sitzungstokens verwendet, um die Abfrage- und Auswahlphasen einer Nutzeranfrage zur automatischen Vervollständigung zu Abrechnungszwecken zu einer separaten Sitzung zusammenzufassen. Die Sitzung beginnt, wenn die Der Nutzer beginnt mit der Eingabe einer Suchanfrage und endet, wenn er einen Ort auswählt. Jede Sitzung kann mehrere Abfragen enthalten, gefolgt von einer Ortsauswahl. Sobald eine Sitzung beendet wird, ist das Token nicht mehr gültig. Ihre App muss für jede Sitzung ein neues Token generieren. Wir empfehlen, Sitzungstokens für alle programmatischen Sitzungen zu verwenden, bei denen eine automatische Vervollständigung erfolgt. Wenn Sie ein Fragment einbetten oder die automatische Vervollständigung mithilfe eines Intents starten, übernimmt die API dies automatisch.

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

  Rufen Sie zum Festlegen des Sitzungstoken-Parameters die Methode setSessionToken() auf. beim Erstellen des FindAutocompletePredictionsRequest-Objekts.

  Weitere Informationen finden Sie unter Sitzungstokens.

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

Standortbeschränkung und Standortgewichtung verwenden

Bei „Autocomplete (New)“ wird standardmäßig die IP-Gewichtung verwendet. den Suchbereich anpassen. Bei der IP-Gewichtung verwendet die API die IP-Adresse der verwendet, um die Ergebnisse zu gewichten. Sie können optional die Standortbeschränkung oder die Standortvorgabe verwenden, um einen Suchbereich anzugeben. Sie können jedoch nicht beides verwenden.

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

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Bei der Standortgewichtung dient der Standort als Verzerrung, d. h. Ergebnisse um den angegebene Position zurückgegeben werden kann, einschließlich Ergebnissen außerhalb des angegebenen Bereich. Im nächsten Beispiel wird die Standortgewichtung für die vorherige Anfrage geändert:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Primäre Typen verwenden

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

Im folgenden Beispiel wird der Abfragestring „Fußball“ angegeben. und verwendet die primäre types-Parameter, um Ergebnisse auf Einrichtungen des Typs zu beschränken "sporting_goods_store":

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Wenn Sie den Parameter „primary_types“ weglassen, können die Ergebnisse Einrichtungen eines Typs enthalten, den Sie möglicherweise nicht möchten, z. B. "athletic_field".

Ursprung verwenden

Wenn Sie den Parameter origin in die Anfrage aufnehmen, der als Breiten- und Längengrad angegeben ist, enthält die API die Luftlinie vom Startpunkt zum Ziel in der Antwort (Zugriff über getDistanceMeters()). In diesem Beispiel wird der Startpunkt auf das Zentrum von San Francisco festgelegt:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Attribution

Sie können „Autocomplete (New)“ auch ohne Karte verwenden. Wenn aber es muss eine Google Maps-Karte sein. Wenn Sie Vorhersagen von „Autocomplete (New)“ ohne Karte verwenden, können Sie muss das Google-Logo enthalten, das im Suchfeld bzw. in den Suchergebnissen angezeigt wird. Weitere Informationen finden Sie unter Google-Logo und Quellenangaben anzeigen.