Einführung
Autocomplete (New) ist ein Webdienst, der als Antwort auf eine HTTP-Anfrage Ortsvorschläge und Suchvorschläge zurückgibt. Geben Sie in der Anfrage einen Suchstring und geografische Grenzen an, die den Suchbereich einschränken.
Autocomplete (New) findet Übereinstimmungen mit vollständigen Wörtern und Teilstrings der Eingabe, sodass sich Ortsnamen, Adressen und Plus Codes zuordnen lassen. Anwendungen können Abfragen senden, während der Nutzer tippt, und schon bei der Eingabe Orts- und Suchvorschläge ausgeben.
Die Antwort von „Automatische Vervollständigung (New)“ kann zwei Arten von Vervollständigungen enthalten:
- Ortsvorschläge: Orte wie Unternehmen, Adressen und POIs, die auf dem angegebenen Eingabetextstring und dem Suchbereich basieren. Ortsvorschläge werden standardmäßig zurückgegeben.
- Suchvorschläge: Abfragestrings, die mit dem eingegebenen Textstring und dem Suchbereich übereinstimmen. Suchvorschläge werden standardmäßig nicht zurückgegeben. Verwenden Sie den Anfrageparameter
includeQueryPredictions, um der Antwort Suchvorschläge hinzuzufügen.
Sie rufen beispielsweise Autocomplete (New) mit einem String auf, der eine unvollständige Nutzereingabe enthält, z. B. „Sicilian piz“, und beschränken den Suchbereich auf San Francisco, Kalifornien. Die Antwort enthält dann eine Liste mit Ortsvorschlägen, die dem Suchstring und dem Suchbereich entsprechen, z. B. das Restaurant „Sicilian Pizza Kitchen“, sowie Details zum Ort.
Die zurückgegebenen Ortsvorschläge sollen dem Nutzer angezeigt 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 Ortsvorschlägen zu erhalten.
Die Antwort kann auch eine Liste von Suchvorschlägen enthalten, die dem Suchstring und dem Suchbereich entsprechen, z. B. „Sizilianische Pizza und Pasta“. Jede Suchanfragenvervollständigung in der Antwort enthält das Feld text mit einem empfohlenen Suchstring für die Textsuche. Verwenden Sie diesen String als Eingabe für Text Search (New), um eine detailliertere Suche durchzuführen.
Mit dem APIs Explorer können Sie Liveanfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen:
Autocomplete (New)-Anfragen
Eine Autocomplete (New)-Anfrage ist eine HTTP-POST-Anfrage an eine URL im folgenden Format:
https://places.googleapis.com/v1/places:autocomplete
Übergeben Sie alle Parameter im JSON-Anfragetext oder in Headern als Teil der POST-Anfrage. Beispiel:
curl -X POST -d '{
"input": "pizza",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7937,
"longitude": -122.3965
},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
Unterstützte Parameter
Parameter |
Beschreibung |
|---|---|
Textstring, nach dem gesucht werden soll (vollständige Wörter, Teilstrings, Ortsnamen, Adressen, Plus Codes). |
|
|
Durch Kommas getrennte Liste, in der angegeben wird, welche Felder in der Antwort zurückgegeben werden sollen. |
Beschränkt die Ergebnisse auf Orte, die einem von bis zu fünf angegebenen primären Typen entsprechen. |
|
Wenn „true“, werden Unternehmen ohne physischen Standort (Unternehmen ohne festen Standort in einem Einzugsgebiet) einbezogen. Die Standardeinstellung ist "false". |
|
Wenn „true“, werden sowohl Orts- als auch Suchvorschläge in die Antwort aufgenommen. Die Standardeinstellung ist "false". |
|
Array mit bis zu 15 zweistelligen Ländercodes, auf die die Ergebnisse beschränkt werden sollen. |
|
Nullbasierter Unicode-Zeichen-Offset der Cursorposition innerhalb des Eingabestrings, der die Vervollständigungen beeinflusst. Die Standardeinstellung ist die Eingabelänge. |
|
Bevorzugte Sprache (IETF BCP-47-Code) für Ergebnisse. Die Standardeinstellung ist der Accept-Language-Header oder „en“. |
|
Gibt einen Bereich (Kreis oder Rechteck) an, auf den die Suchergebnisse ausgerichtet werden sollen. Ergebnisse außerhalb des Bereichs sind zulässig. Kann nicht mit „locationRestriction“ verwendet werden. |
|
Gibt einen Bereich (Kreis oder Rechteck) an, auf den die Suchergebnisse beschränkt werden sollen. Ergebnisse außerhalb dieses Bereichs werden ausgeschlossen. Kann nicht mit „locationBias“ verwendet werden. |
|
Ausgangspunkt (Breitengrad, Längengrad), der zur Berechnung der Luftlinie (distanceMeters) zu vorhergesagten Zielen verwendet wird. |
|
Regionscode, der zum Formatieren der Antwort und zum Beeinflussen von Vorschlägen verwendet wird (z.B. „uk“, „fr“). |
|
Vom Nutzer generierter String, um Autocomplete-Aufrufe zu Abrechnungszwecken in einer Sitzung zu gruppieren. |
Informationen zur Antwort
Autocomplete (New) gibt ein JSON-Objekt als Antwort zurück. Die Antwort sieht so aus:
- Das Array
suggestionsenthält alle vorhergesagten Orte und Suchanfragen, sortiert nach ihrer Relevanz. Jeder Ort wird durch einplacePrediction-Feld und jede Abfrage durch einqueryPrediction-Feld dargestellt. - Ein
placePrediction-Feld enthält detaillierte Informationen zu einer einzelnen Ortsvervollständigung, einschließlich der Orts-ID und der Textbeschreibung.- Damit die Textbeschreibung einer Ortsvorhersage besser mit der Nutzereingabe im Parameter
inputübereinstimmt, kann sie alternative Namen für Orte, Straßen und andere Adresskomponenten enthalten. Diese alternativen Namen können sich von den Namen unterscheiden, die in den FelderndisplayNameund „address“ der Place Details-Ergebnisse für dieselbe Orts-ID zurückgegeben werden. - In diesem Kontext können alternative Namen für einige Orte in einer anderen Sprache als der im Parameter
languageCodeangegebenen Sprache sein, je nachdem, welche Namen besser zur Nutzereingabe passen.
- Damit die Textbeschreibung einer Ortsvorhersage besser mit der Nutzereingabe im Parameter
- Ein
queryPrediction-Feld enthält detaillierte Informationen zu einer einzelnen Abfragevorhersage.
Das vollständige JSON-Objekt hat folgendes Format:
{
"suggestions": [
{
"placePrediction": {
"place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko",
"placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko",
"text": {
"text": "Amoeba Music, Haight Street, San Francisco, CA, USA",
"matches": [
{
"endOffset": 6
}]
},
...
},
{
"queryPrediction": {
"text": {
"text": "Amoeba Music",
"matches": [
{
"endOffset": 6
}]
},
...
}
...]
}Erforderliche Parameter
Eingabe
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 diesem String zurück und sortiert die Ergebnisse nach ihrer Relevanz.
Optionale Parameter
FieldMask
Geben Sie die Liste der Felder an, die in der Antwort zurückgegeben werden sollen, indem Sie eine Antwortfeldmaske erstellen. Übergeben Sie die Antwortfeldmaske mit dem HTTP-Header X-Goog-FieldMask an die Methode.
Geben Sie eine durch Kommas getrennte Liste der Vorschlagsfelder an, die zurückgegeben werden sollen. Beispiel: Zum Abrufen von suggestions.placePrediction.text.text und suggestions.queryPrediction.text.text des Vorschlags.
X-Goog-FieldMask: suggestions.placePrediction.text.text,suggestions.queryPrediction.text.text
Verwenden Sie *, um alle Felder abzurufen.
X-Goog-FieldMask: *
includeFutureOpeningBusinesses
Wenn true, werden Unternehmen zurückgegeben, die voraussichtlich in Zukunft eröffnet werden. Die Standardeinstellung ist false.
includedPrimaryTypes
Ein Ort kann nur einen einzigen primären Typ aus den in Tabelle A oder Tabelle B aufgeführten Typen haben. Der primäre Typ könnte beispielsweise "mexican_restaurant" oder "steak_house" sein.
Standardmäßig gibt die API alle Orte basierend auf dem Parameter input zurück, unabhängig vom primären Typwert, der dem Ort zugeordnet ist. Sie können die Ergebnisse auf einen oder mehrere bestimmte primäre Typen beschränken, indem Sie den Parameter includedPrimaryTypes übergeben.
Mit diesem Parameter können Sie bis zu fünf Typwerte aus Tabelle A oder Tabelle B angeben. Ein Ort muss mit einem der angegebenen primären Typwerte übereinstimmen, damit er in die Antwort aufgenommen wird.
Dieser Parameter kann stattdessen auch (regions) oder (cities) enthalten. Die Sammlung vom Typ (regions) filtert nach Gebieten oder Bereichen, z. B. Stadtteilen und Postleitzahlen. Mit der Typensammlung (cities) wird nach Orten gefiltert, die von Google als Stadt identifiziert werden.
Die Anfrage wird mit dem Fehler INVALID_REQUEST abgelehnt, wenn:
- Es wurden mehr als fünf Typen angegeben.
- Zusätzlich zu
(cities)oder(regions)wird ein beliebiger Typ angegeben. - Sie haben einen unbekannten Typ angegeben.
includePureServiceAreaBusinesses
Wenn der Wert auf true gesetzt ist, enthält die Antwort Unternehmen, die Kunden direkt besuchen oder beliefern, aber keinen festen Standort haben. Wenn der Wert auf false festgelegt ist, gibt die API nur Unternehmen mit einem physischen Standort zurück.
includeQueryPredictions
Wenn true, enthält die Antwort sowohl Orts- als auch Suchvorschläge. Der Standardwert ist false. Das bedeutet, dass die Antwort nur Ortsvorschläge enthält.
includedRegionCodes
Es werden nur Ergebnisse aus der Liste der angegebenen Regionen berücksichtigt, die als Array mit bis zu 15 ccTLD-Werten („Top-Level-Domain“) mit zwei Zeichen angegeben sind. Wenn sie weggelassen wird, werden keine Einschränkungen auf die Antwort angewendet. So beschränken Sie die Regionen beispielsweise auf Deutschland und Frankreich:
"includedRegionCodes": ["de", "fr"]
Wenn Sie sowohl locationRestriction als auch includedRegionCodes angeben, befinden sich die Ergebnisse im Schnittbereich der beiden Einstellungen.
inputOffset
Der nullbasierte Unicode-Zeichen-Offset, der die Cursorposition in input angibt.
Die Cursorposition kann beeinflussen, welche Vervollständigungen zurückgegeben werden. Wenn das Feld leer ist, wird standardmäßig die Länge von input verwendet.
languageCode
Die bevorzugte Sprache, in der Ergebnisse zurückgegeben werden sollen. Die Ergebnisse können in verschiedenen Sprachen vorliegen, wenn die in input verwendete Sprache von dem durch languageCode angegebenen Wert abweicht oder wenn für den zurückgegebenen Ort keine Übersetzung aus der Landessprache in languageCode vorhanden ist.
- Sie müssen IETF BCP-47-Sprachcodes verwenden, um die bevorzugte Sprache anzugeben.
-
Wenn
languageCodenicht angegeben ist, verwendet die API den im HeaderAccept-Languageangegebenen Wert. Wenn keines von beiden angegeben ist, wird standardmäßigenverwendet. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API den FehlerINVALID_ARGUMENTzurück. - Die bevorzugte Sprache hat einen geringen Einfluss auf die von der API zurückgegebenen Ergebnisse und die Reihenfolge, in der sie zurückgegeben werden. Dies wirkt sich auch auf die Fähigkeit der API aus, Rechtschreibfehler zu korrigieren.
-
Ortsvorschläge werden je nach Nutzereingabe in der jeweiligen Anfrage unterschiedlich formatiert.
-
Zuerst werden übereinstimmende Begriffe im Parameter
inputausgewählt. Dabei werden Namen verwendet, die der im ParameterlanguageCodeangegebenen Spracheinstellung entsprechen, sofern verfügbar. Andernfalls werden Namen verwendet, die am besten zur Nutzereingabe passen. -
Ortsnamen können mit alternativen Namen formatiert werden, die mit Begriffen im Parameter
inputübereinstimmen, einschließlich Namen in anderen Sprachen als der im ParameterlanguageCodeangegebenen Sprache. -
Adressen werden in der Landessprache und, wenn möglich, in einer für den Nutzer lesbaren Schrift formatiert, nachdem übereinstimmende Begriffe ausgewählt wurden, die den Begriffen im Parameter
inputentsprechen. -
Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben, nachdem übereinstimmende Begriffe ausgewählt wurden, die den Begriffen im Parameter
inputentsprechen. Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die nächstgelegene Übereinstimmung.
-
Zuerst werden übereinstimmende Begriffe im Parameter
locationBias oder locationRestriction
Sie können entweder locationBias oder locationRestriction angeben, um den Suchbereich zu definieren, aber nicht beides. Mit locationRestriction wird die Region angegeben, in der die Ergebnisse liegen müssen. Mit locationBias wird die Region angegeben, in deren Nähe die Ergebnisse liegen müssen, aber auch außerhalb des Bereichs liegen können.
locationBias
Gibt einen Bereich für die Suche an. Dieser Standort dient 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.
locationRestriction
Gibt einen Bereich für die Suche an. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben.
Geben Sie die Region locationBias oder locationRestriction 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
locationRestrictionmüssen Sie den Radius auf einen Wert größer als 0,0 festlegen. Andernfalls werden keine Ergebnisse zurückgegeben.Beispiel:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Ein Rechteck ist ein Darstellungsbereich mit Breiten- und Längengrad, der durch zwei diagonal gegenüberliegende
low- und Höhepunkte dargestellt wird. Ein Darstellungsbereich gilt als geschlossene Region, d. h., er umfasst auch seine Grenze. 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:- Wenn
low=highist, besteht der Darstellungsbereich aus diesem einzelnen Punkt. - Wenn
low.longitude>high.longitude, wird der Längengradbereich invertiert (der Darstellungsbereich kreuzt den 180-Grad-Längengrad). - Wenn
low.longitude= -180 Grad undhigh.longitude= 180 Grad ist, umfasst der Darstellungsbereich alle Längengrade. - Wenn
low.longitude= 180 Grad undhigh.longitude= -180 Grad ist, ist der Längengradbereich leer.
Sowohl
lowals auchhighmüssen ausgefüllt sein und das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.Dieser Darstellungsbereich umschließt beispielsweise New York City vollständig:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Wenn
origin
Der Ausgangspunkt, von dem aus die Luftlinie zum Ziel berechnet werden soll (zurückgegeben als distanceMeters). Wenn dieser Wert weggelassen wird, wird die Luftlinie nicht zurückgegeben. Muss als Breiten- und Längengradkoordinaten angegeben werden:
"origin": { "latitude": 40.477398, "longitude": -74.259087 }
regionCode
Der Regionscode, der zum Formatieren der Antwort verwendet wird, 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).
Vorschläge werden auch basierend auf Regionscodes angepasst. Google empfiehlt, die regionCode entsprechend den regionalen Einstellungen des Nutzers festzulegen.
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 regionCode festlegen, wird bei Vervollständigungen innerhalb dieser Region möglicherweise der Ländername im Vorschlagstext weggelassen. Das bedeutet, dass structuredFormat.secondaryText möglicherweise nicht vorhanden ist. Achten Sie daher darauf, dass Ihre Anwendung Fälle verarbeitet, in denen secondaryText nicht definiert ist oder fehlt.
sessionToken
Sitzungstokens sind vom Nutzer generierte Strings, mit denen Autocomplete (New)-Aufrufe als „Sitzungen“ erfasst werden. Bei Autocomplete (New) werden Sitzungstokens verwendet, um die Abfrage- und Auswahlphasen einer Nutzeranfrage zur automatischen Vervollständigung zu Abrechnungszwecken zu einer separaten Sitzung zusammenzufassen. Weitere Informationen finden Sie unter Sitzungstokens.
Parameter zum Beeinflussen der Ergebnisse auswählen
Die Parameter von Autocomplete (New) können die Suchergebnisse unterschiedlich beeinflussen. Die folgende Tabelle enthält Empfehlungen zur Verwendung von Parametern basierend auf dem beabsichtigten Ergebnis.| Parameter | Nutzungsempfehlung |
|---|---|
regionCode
|
Wird gemäß den regionalen Einstellungen des Nutzers festgelegt. |
includedRegionCodes
|
Wird festgelegt, um die Ergebnisse auf die Liste der angegebenen Regionen zu beschränken. |
locationBias
|
Verwenden Sie diese Option, wenn Ergebnisse in oder um eine Region bevorzugt werden. Definieren Sie die Region gegebenenfalls als den Darstellungsbereich der Karte, die sich der Nutzer ansieht. |
locationRestriction
|
Verwenden Sie diese Option nur, wenn Ergebnisse außerhalb einer Region nicht zurückgegeben werden sollen. |
origin
|
Verwenden Sie diese Option, wenn die Luftlinie zu jeder Vorhersage gewünscht ist. |
Beispiele für Autocomplete (New)
Suche mit „locationRestriction“ auf einen Bereich beschränken
Mit locationRestriction wird der Suchbereich angegeben. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Im folgenden Beispiel wird locationRestriction verwendet, um die Anfrage auf einen Kreis mit einem Radius von 5.000 Metern um San Francisco zu beschränken:
curl -X POST -d '{
"input": "Art museum",
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
Alle Ergebnisse aus den angegebenen Bereichen sind im Array suggestions enthalten:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "establishment", "museum", "point_of_interest" ] } }, { "placePrediction": { "place": "places/ChIJI7NivpmAhYARSuRPlbbn_2w", "placeId": "ChIJI7NivpmAhYARSuRPlbbn_2w", "text": { "text": "de Young Museum, Hagiwara Tea Garden Drive, San Francisco, CA, USA", "matches": [ { "endOffset": 15 } ] }, "structuredFormat": { "mainText": { "text": "de Young Museum", "matches": [ { "endOffset": 15 } ] }, "secondaryText": { "text": "Hagiwara Tea Garden Drive, San Francisco, CA, USA" } }, "types": [ "establishment", "point_of_interest", "tourist_attraction", "museum" ] } }, /.../ ] }
Sie können auch locationRestriction verwenden, um die Suche auf einen rechteckigen Darstellungsbereich zu beschränken. Im folgenden Beispiel wird die Anfrage auf die Innenstadt von San Francisco beschränkt:
curl -X POST -d '{
"input": "Art museum",
"locationRestriction": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
Die Ergebnisse sind im Array suggestions enthalten:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJkQQVTZqAhYARHxPt2iJkm1Q", "placeId": "ChIJkQQVTZqAhYARHxPt2iJkm1Q", "text": { "text": "Asian Art Museum, Larkin Street, San Francisco, CA, USA", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "structuredFormat": { "mainText": { "text": "Asian Art Museum", "matches": [ { "startOffset": 6, "endOffset": 16 } ] }, "secondaryText": { "text": "Larkin Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "museum", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJyQNK-4SAhYARO2DZaJleWRc", "placeId": "ChIJyQNK-4SAhYARO2DZaJleWRc", "text": { "text": "International Art Museum of America, Market Street, San Francisco, CA, USA", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "structuredFormat": { "mainText": { "text": "International Art Museum of America", "matches": [ { "startOffset": 14, "endOffset": 24 } ] }, "secondaryText": { "text": "Market Street, San Francisco, CA, USA" } }, "types": [ "museum", "point_of_interest", "tourist_attraction", "art_gallery", "establishment" ] } } ] }
Suche mit „locationBias“ auf einen Bereich eingrenzen
Bei locationBias 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 folgenden Beispiel wird die Anfrage auf die Innenstadt von San Francisco ausgerichtet:
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
Die Ergebnisse enthalten jetzt viel mehr Elemente, einschließlich Ergebnisse außerhalb des Radius von 5.000 Metern:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "store", "establishment", "home_goods_store" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "electronics_store", "point_of_interest", "establishment", "home_goods_store", "store" ] } }, ... ] }
Sie können auch locationBias verwenden, um die Suche auf einen rechteckigen Darstellungsbereich zu beschränken. Im folgenden Beispiel wird die Anfrage auf die Innenstadt von San Francisco beschränkt:
curl -X POST -d '{
"input": "Amoeba",
"locationBias": {
"rectangle": {
"low": {
"latitude": 37.7751,
"longitude": -122.4219
},
"high": {
"latitude": 37.7955,
"longitude": -122.3937
}
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
In der Antwort werden zwar Suchergebnisse innerhalb des rechteckigen Darstellungsbereichs angezeigt, aufgrund der Gewichtung liegen jedoch einige Ergebnisse außerhalb der definierten Grenzen. Die Ergebnisse sind auch im suggestions-Array enthalten:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJr7uwwy58hYARBY-e7-QVwqw", "placeId": "ChIJr7uwwy58hYARBY-e7-QVwqw", "text": { "text": "Amoeba Music, Telegraph Avenue, Berkeley, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Telegraph Avenue, Berkeley, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, { "placePrediction": { "place": "places/ChIJRdmfADq_woARYaVhnfQSUTI", "placeId": "ChIJRdmfADq_woARYaVhnfQSUTI", "text": { "text": "Amoeba Music, Hollywood Boulevard, Los Angeles, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Hollywood Boulevard, Los Angeles, CA, USA" } }, "types": [ "point_of_interest", "store", "establishment" ] } }, /.../ ] }
„includedPrimaryTypes“ verwenden
Verwenden Sie den Parameter includedPrimaryTypes, um bis zu fünf Typwerte aus Tabelle A, Tabelle B, nur (regions) oder nur (cities) anzugeben. Ein Ort muss mit einem der angegebenen primären Typwerte übereinstimmen, damit er in die Antwort aufgenommen wird.
Im folgenden Beispiel geben Sie den input-String „Soccer“ an und verwenden den Parameter includedPrimaryTypes, um die Ergebnisse auf Einrichtungen vom Typ "sporting_goods_store" zu beschränken:
curl -X POST -d '{
"input": "Soccer",
"includedPrimaryTypes": ["sporting_goods_store"],
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 500.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
Wenn Sie den Parameter includedPrimaryTypes weglassen, können die Ergebnisse auch Orte eines Typs enthalten, den Sie nicht möchten, z. B. "athletic_field".
Abfragevorhersagen anfordern
Suchvorschläge werden standardmäßig nicht zurückgegeben. Verwenden Sie den Anfrageparameter includeQueryPredictions, um der Antwort Suchvorschläge hinzuzufügen. Beispiel:
curl -X POST -d '{
"input": "Amoeba",
"includeQueryPredictions": true,
"locationBias": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
Das Array suggestions enthält jetzt sowohl Orts- als auch Suchvorschläge, wie oben unter Informationen zur Antwort beschrieben. Jede Vervollständigung enthält das Feld text mit einem empfohlenen Suchstring für die Textsuche. Sie können eine Text Search (New)-Anfrage stellen, um weitere Informationen zu den zurückgegebenen vervollständigten Suchanfragen zu erhalten.
Ursprung verwenden
In diesem Beispiel wird origin in der Anfrage als Breiten- und Längengradkoordinaten angegeben. Wenn Sie origin angeben, enthält die Antwort von „Autocomplete (New)“ das Feld distanceMeters mit der Luftlinie von origin zum Ziel. In diesem Beispiel wird der Ursprung auf das Zentrum von San Francisco festgelegt:
curl -X POST -d '{
"input": "Amoeba",
"origin": {
"latitude": 37.7749,
"longitude": -122.4194
},
"locationRestriction": {
"circle": {
"center": {
"latitude": 37.7749,
"longitude": -122.4194
},
"radius": 5000.0
}
}
}' \
-H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \
https://places.googleapis.com/v1/places:autocomplete
Die Antwort enthält jetzt distanceMeters:
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJ5YQQf1GHhYARPKG7WLIaOko", "placeId": "ChIJ5YQQf1GHhYARPKG7WLIaOko", "text": { "text": "Amoeba Music, Haight Street, San Francisco, CA, USA", "matches": [ { "endOffset": 6 } ] }, "structuredFormat": { "mainText": { "text": "Amoeba Music", "matches": [ { "endOffset": 6 } ] }, "secondaryText": { "text": "Haight Street, San Francisco, CA, USA" } }, "types": [ "home_goods_store", "establishment", "point_of_interest", "store", "electronics_store" ], "distanceMeters": 3012 } } ] }
Unternehmen finden, die in Zukunft eröffnen
Das folgende Beispiel zeigt eine Autocomplete (New)-Anfrage für Unternehmen, die in Zukunft in New Meadows, Idaho, USA, eröffnet werden:
curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-d '{
"input": "Roberts Greenhouse and Tree Farm",
"includeFutureOpeningBusinesses": true,
"locationBias": {
"circle": {
"center": {"latitude": 44.9755100, "longitude": -116.2842180},
"radius": 20
}
}
}' \
"https://places.googleapis.com/v1/places:autocomplete"
Die Antwort enthält Details zum Ort, aber nicht das Eröffnungsdatum.
{ "suggestions": [ { "placePrediction": { "place": "places/ChIJp1-VoKWJplQRMz8g-7Wa3Do", "placeId": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "text": { "text": "Roberts Greenhouse and Tree Farm, McLain Street, New Meadows, ID, USA", "matches": [ { "endOffset": 32 } ] }, "structuredFormat": { "mainText": { "text": "Roberts Greenhouse and Tree Farm", "matches": [ { "endOffset": 32 } ] }, "secondaryText": { "text": "McLain Street, New Meadows, ID, USA" } }, "types": [ "garden_center", "establishment", "service", "store", "point_of_interest" ] } } ] }
Entfernung fehlt in der Antwort
In bestimmten Fällen fehlt distanceMeters im Antworttext, auch wenn origin in der Anfrage enthalten ist. Dies kann in den folgenden Fällen passieren:
distanceMetersist fürroute-Vorhersagen nicht enthalten.distanceMetersist nicht enthalten, wenn der Wert0ist. Das ist der Fall, wenn die Vorhersagen weniger als 1 Meter vom angegebenenorigin-Standort entfernt sind.
Clientbibliotheken, die versuchen, das Feld distanceMeters aus einem geparsten Objekt zu lesen, geben ein Feld mit dem Wert 0 zurück. Um Nutzer nicht in die Irre zu führen, sollten Sie keine Entfernung von null anzeigen.
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.
| 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.1
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).1
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.
1
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 Felder 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 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.1
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.
- 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.
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.
Testen!
Mit dem APIs Explorer können Sie Beispielanfragen erstellen, um sich mit der API und den API-Optionen vertraut zu machen.
Wählen Sie rechts auf der Seite das API-Symbol api aus.
Bearbeiten Sie optional die Anfrageparameter.
Wählen Sie den Button Ausführen aus. Wählen Sie im Dialogfeld das Konto aus, das Sie für die Anfrage verwenden möchten.
Wählen Sie im APIs Explorer-Bereich das Vollbildsymbol fullscreen aus, um das APIs Explorer-Fenster zu maximieren.