Der Dienst „Autocomplete (New)“ ist ein Webdienst, der als Antwort auf eine HTTP-Anfrage Orts- und Abfragevorhersagen zurückgibt. Geben Sie in der Anfrage einen Suchstring für Text sowie geografische Grenzen an, die den Suchbereich steuern.
Der Dienst „Autocomplete (New)“ kann einen Abgleich mit vollständigen Wörtern und Teilstrings der Eingabe durchführen, um Ortsnamen, Adressen und Plus Codes aufzulösen. Anwendungen können daher Abfragen senden, während der Nutzer tippt, um spontan Orts- und Abfragevorhersagen bereitzustellen.
Die Antwort der Autocomplete (New) API kann zwei Arten von Vorhersagen enthalten:
- Vervollständigungen von Orten: Orte wie Unternehmen, Adressen und POIs, basierend auf dem angegebenen Textstring und Suchbereich. Vorschläge für Orte werden standardmäßig zurückgegeben.
- Abfragevorhersagen: Abfragestrings, die mit dem Eingabetextstring und dem Suchbereich übereinstimmen. Abfragevorhersagen werden standardmäßig nicht zurückgegeben. Verwenden Sie den Anfrageparameter
includeQueryPredictions
, um der Antwort Abfragevorhersagen hinzuzufügen.
Beispiel: Sie rufen die API auf und verwenden als Eingabe einen String, der die teilweise Nutzereingabe "Sicilian piz" enthält, wobei der Suchbereich auf San Francisco, CA beschränkt ist. Die Antwort enthält dann eine Liste mit Ortsvorschlägen, die dem Suchstring und dem Suchbereich entsprechen, z. B. das Restaurant „Sicilian Pizza Kitchen“, sowie Details zum Ort.
Die zurückgegebenen Ortsvorschläge sollen dem Nutzer angezeigt werden, um ihm bei der Auswahl des gewünschten Ortes zu helfen. Sie können eine Place Details (New)-Anfrage stellen, um weitere Informationen zu zurückgegebenen Ortsvorschlägen zu erhalten.
Die Antwort kann auch eine Liste von Abfragevorhersagen enthalten, die dem Suchstring und dem Suchbereich entsprechen, z. B. „Sizilianische Pizza & Pasta“. Jede Abfragevorhersage in der Antwort enthält das Feld text
mit einem empfohlenen Textsuchstring. Verwenden Sie diesen String als Eingabe für Text Search (New), um eine detailliertere Suche durchzuführen.
Autocomplete-Anfragen (neu)
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
Anfrage mit der automatischen Vervollständigung stellen (neu)
Die Places API unterstützt die vorhandenen APIs Autocomplete und Query Autocomplete. Wenn Sie mit diesen APIs vertraut sind, werden in der Vorabversion von „Autocomplete (New)“ die folgenden Änderungen vorgenommen:- Die neue automatische Vervollständigung verwendet HTTP-POST-Anfragen. Übergeben Sie Parameter im Anfragetext oder in Headern als Teil einer HTTP-POST-Anfrage. Im Gegensatz dazu übergeben Sie bei den vorhandenen APIs URL-Parameter mit einer HTTP-GET-Anfrage.
- Die neue Autocomplete-Funktion unterstützt sowohl API-Schlüssel als auch OAuth als Authentifizierungsmechanismus.
- In der neuen automatischen Vervollständigung wird als Antwortformat nur JSON unterstützt.
In der folgenden Tabelle sind Parameter in den bestehenden APIs für die automatische Vervollständigung und Query Autocomplete aufgeführt, die für die neue automatische Vervollständigung umbenannt oder geändert wurden, sowie Parameter, die nicht mehr unterstützt werden.
Aktueller Parameter | Neuer Parameter | Hinweise |
---|---|---|
components |
includedRegionCodes |
|
language |
languageCode |
|
location |
locationBias |
|
ipbias |
Wenn Sie sowohl locationBias als auch locationRestriction weglassen, verwendet die API standardmäßig die IP-Gewichtung. |
|
offset |
inputOffset |
|
radius |
locationBias oder locationRestriction |
|
region |
regionCode |
|
stricbounds |
locationRestriction |
|
sessiontoken |
sessionToken |
|
types |
includedPrimaryTypes |
Nutzungslimits
In der Vorabversion sind maximal 600 Abfragen pro Minute und Projekt möglich.
Supportoptionen für Vorabversionen
Obwohl Google nicht verpflichtet ist, Support für Vorabversionen, Features oder Funktionen der Dienste bereitzustellen, werden Anfragen in diesen Entwicklungsphasen von Fall zu Fall berücksichtigt.
- Vorabversionen sind nicht durch das SLA für die Google Maps Platform abgedeckt.
- Die Verwendung von Fallback-Mechanismen wird empfohlen, insbesondere wenn Sie eine Vorabveröffentlichung in einer Produktionsumgebung verwenden. Beispiele für Fallback-Situationen sind: Kontingentüberschreitung, unerwartete Antwortcodes und Latenz oder unerwartete Antworten im Vergleich zur vorhandenen automatischen Vervollständigung.
Über den Issue Tracker können Sie neue Funktionen oder Änderungen an vorhandenen Funktionen vorschlagen. Bitte beschreiben Sie die spezifische Funktionalität, die Ihrer Meinung nach hinzugefügt werden sollte, und geben Sie die Gründe dafür an, die Sie für wichtig halten. Wenn möglich, machen Sie spezifische Details zu Ihrem Anwendungsfall und den neuen Möglichkeiten, die diese Funktion bietet:
Bei allen anderen Fragen zu Funktionen senden Sie eine E-Mail an newplacesapi@google.com.
Informationen zur Antwort
„Autocomplete (New)“ gibt ein JSON-Objekt als Antwort zurück. In der Antwort:
- Das Array
suggestions
enthält alle vorgeschlagenen Orte und Suchanfragen in der Reihenfolge ihrer wahrgenommenen Relevanz. Jeder Ort wird durch das FeldplacePrediction
und jede Abfrage durch das FeldqueryPrediction
dargestellt. - Das Feld
placePrediction
enthält detaillierte Informationen zu einem einzelnen Ortsvorschlag, einschließlich der Orts-ID und Textbeschreibung. - Das Feld
queryPrediction
enthält detaillierte Informationen zu einer einzelnen Abfragevorhersage.
Das vollständige JSON-Objekt hat das folgende 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
Die Textzeichenfolge, nach der gesucht werden soll. Geben Sie vollständige Wörter und Teilstrings, Ortsnamen, Adressen und Plus Codes an. Der Dienst „Autocomplete (New)“ gibt mögliche Übereinstimmungen basierend auf diesem String zurück und sortiert die Ergebnisse nach ihrer erkannten Relevanz.
Optionale Parameter
-
includedPrimaryTypes
Ein Ort kann nur einen einzelnen primären Typ aus den Typen Tabelle A oder Tabelle B haben. Der primäre Typ kann 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. Beschränken Sie die Ergebnisse auf einen bestimmten primären Typ oder primäre Typen. Übergeben Sie dazu den ParameterincludedPrimaryTypes
.Mit diesem Parameter können Sie bis zu fünf Typwerte aus Tabelle A oder Tabelle B angeben. Ein Ort muss einem der angegebenen primären Typwerte entsprechen, um in die Antwort aufgenommen zu werden.
In folgenden Fällen wird die Anfrage mit dem Fehler
INVALID_REQUEST
abgelehnt:- Es sind mehr als fünf Typen angegeben.
- Alle nicht erkannten Typen sind angegeben.
-
includeQueryPredictions
Bei
true
enthält die Antwort sowohl Orts- als auch Abfragevorhersagen. Der Standardwert istfalse
, d. h. die Antwort enthält nur Vorschläge für Orte. -
includedRegionCodes
Es werden nur Ergebnisse aus der Liste der angegebenen Regionen berücksichtigt, die als Array aus bis zu 15 zweistelligen ccTLD-Werten („Top-Level-Domain“) angegeben werden. Wenn diese Angabe weggelassen wird, werden keine Einschränkungen auf die Antwort angewendet. So beschränken Sie beispielsweise die Regionen auf Deutschland und Frankreich:
"includedRegionCodes": ["de", "fr"]
Wenn Sie sowohl
locationRestriction
als auchincludedRegionCodes
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 Vorhersagen zurückgegeben werden. Wenn das Feld leer ist, wird standardmäßig die Längeinput
verwendet. -
languageCode
Die bevorzugte Sprache, in der Ergebnisse zurückgegeben werden sollen. Die Ergebnisse können in gemischten Sprachen vorliegen, wenn die in
input
verwendete Sprache sich von dem durchlanguageCode
angegebenen Wert unterscheidet oder wenn der zurückgegebene Ort keine Übersetzung von der lokalen Sprache inlanguageCode
hat.- Sie müssen die IETF-BCP-47-Sprachcodes verwenden, um die bevorzugte Sprache anzugeben.
-
Ist
languageCode
nicht angegeben, verwendet die API den imAccept-Language
-Header angegebenen Wert. Wenn weder das eine noch das andere angegeben ist, ist der Standardwerten
. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API den FehlerINVALID_ARGUMENT
zurück. - Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnisse, die von der API zurückgegeben werden, sowie die Reihenfolge, in der sie zurückgegeben werden. Dies wirkt sich auch auf die Korrektur von Rechtschreibfehlern durch die API aus.
-
Die API versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für die Bevölkerung vor Ort lesbar ist und gleichzeitig die Nutzereingabe wiedergibt. Ortsvorschläge werden je nach Nutzereingabe bei der jeweiligen Anfrage unterschiedlich formatiert.
-
Übereinstimmende Begriffe im
input
-Parameter werden zuerst ausgewählt. Dabei werden Namen verwendet, die der durch denlanguageCode
-Parameter angegebenen Spracheinstellung (sofern verfügbar) entsprechen. Andernfalls werden Namen verwendet, die am besten zur Nutzereingabe passen. -
Adressen werden erst dann in der lokalen Sprache formatiert, wenn der Nutzer sie nach Möglichkeit in einem Skript lesen kann, nachdem übereinstimmende Begriffe ausgewählt wurden, die mit den Begriffen im
input
-Parameter übereinstimmen. -
Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben, nachdem übereinstimmende Begriffe ausgewählt wurden, die mit den Begriffen im Parameter
input
übereinstimmen. Wenn ein Name nicht in der bevorzugten Sprache verfügbar ist, verwendet die API die höchste Übereinstimmung.
-
Übereinstimmende Begriffe im
locationBias oder locationRestriction
Sie können
locationBias
oderlocationRestriction
angeben, aber nicht beides, um den Suchbereich zu definieren. Stellen Sie sichlocationRestriction
als die Angabe der Region vor, in der sich die Ergebnisse befinden müssen, undlocationBias
als die Angabe der Region, in der sich die Ergebnisse in der Nähe, aber außerhalb dieses Bereichs befinden müssen.locationBias
Gibt einen zu durchsuchenden Bereich an. Dieser Standort dient als Verzerrung, das heißt, dass Ergebnisse rund um den angegebenen Standort zurückgegeben werden können, auch Ergebnisse außerhalb des angegebenen Bereichs.
locationRestriction
Gibt einen zu durchsuchenden Bereich an. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben.
Geben Sie den Bereich
locationBias
oderlocationRestriction
als rechteckigen Darstellungsbereich oder als Kreis an.Ein Kreis wird durch den Mittelpunkt und einen Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 (jeweils einschließlich) liegen. Der Standardwert ist 0,0. Für
locationRestriction
müssen Sie den Radius auf einen Wert größer als 0,0 festlegen. Ansonsten gibt die Anfrage keine Ergebnisse zurück.Beispiel:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Ein Rechteck ist ein Darstellungsbereich für Breiten- und Längengrad, der als zwei diagonal gegenüberliegende
low
- und Höchstwerte dargestellt wird. Ein Darstellungsbereich wird als geschlossener Bereich betrachtet, d. h. er enthält seine Begrenzung. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen und die Längengradgrenzen zwischen -180 und 180 Grad (jeweils einschließlich):- Wenn
low
=high
ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt. - Wenn
low.longitude
>high.longitude
ist, wird der Längengradbereich invertiert (der Darstellungsbereich kreuzt die 180-Grad-Längengradlinie). - Wenn
low.longitude
= -180 Grad undhigh.longitude
= 180 Grad ist, enthält der Darstellungsbereich alle Längengrade. - Wenn
low.longitude
= 180 Grad undhigh.longitude
= -180 Grad ist, ist der Längengradbereich leer.
Sowohl
low
als auchhigh
müssen ausgefüllt werden und das dargestellte Feld darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.Dieser Darstellungsbereich umfasst beispielsweise New York City:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Wenn
-
Ursprung
Der Startpunkt, von dem aus die Luftentfernung zum Ziel berechnet werden soll (zurückgegeben als
distanceMeters
). Wenn dieser Wert weggelassen wird, wird keine Luftlinie zurückgegeben. Diese müssen in Form von Breiten- und Längengrad angegeben werden:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
Der zum Formatieren der Antwort verwendete Regionscode, angegeben als zweistelliger ccTLD-Wert („Top-Level-Domain“). Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes. Es gibt jedoch einige Ausnahmen. 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 „The United Kingdom of Great Britain and Northern Ireland“).
Wenn Sie einen ungültigen Regionscode angeben, gibt die API den Fehler
INVALID_ARGUMENT
zurück. Der Parameter kann sich gemäß anwendbarem Recht auf Ergebnisse auswirken. -
sessionToken
Sitzungstokens sind vom Nutzer generierte Strings, die Aufrufe der automatischen Vervollständigung (New) als „Sitzungen“ erfassen. Die Funktion „Autocomplete (neu)“ verwendet Sitzungstokens, um die Abfrage- und Auswahlphasen einer automatischen Vervollständigung durch den Nutzer zu Abrechnungszwecken in einer separaten Sitzung zu gruppieren. Weitere Informationen finden Sie unter Sitzungstokens.
Beispiele für die automatische Vervollständigung (neu)
„locationRestriction“ und „locationBias“ verwenden
Die API verwendet standardmäßig die IP-Gewichtung, um den Suchbereich zu steuern. Bei der IP-Gewichtung verwendet die API die IP-Adresse des Geräts, um die Ergebnisse zu gewichten. Sie können optional locationRestriction
oder locationBias
, aber nicht beides verwenden, um einen Bereich anzugeben, in dem gesucht werden soll.
locationRestriction
gibt den Bereich an, in dem gesucht werden soll. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben. Im folgenden Beispiel verwenden Sie locationRestriction
, um die Anfrage auf einen Kreis mit einem Radius von 5.000 Metern zu beschränken, der in der Mitte San Francisco liegt:
curl -X POST -d '{ "input": "Amoeba", "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 innerhalb der angegebenen Gebiete sind im Array suggestions
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": [ "home_goods_store", "establishment", "store", "point_of_interest", "electronics_store" ] } } ] }
Bei locationBias
dient der Standort als Gewichtung. Das bedeutet, dass Ergebnisse rund um den angegebenen Standort zurückgegeben werden können, auch Ergebnisse außerhalb des angegebenen Bereichs. Im nächsten Beispiel ändern Sie die Anfrage so, dass sie locationBias
verwendet:
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 viele weitere Elemente, einschließlich Ergebnissen 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" ] } }, ... ] }
EingeschlossenePrimärtypen verwenden
Verwenden Sie den Parameter includedPrimaryTypes
, um die Ergebnisse einer Anfrage auf einen bestimmten Typ einzuschränken, wie in Tabelle A und Tabelle B aufgeführt. Sie können ein Array mit bis zu fünf Werten angeben.
Wenn keine Angabe erfolgt, werden alle Typen zurückgegeben.
Im folgenden Beispiel geben Sie als input
-String „Soccer“ an und verwenden den Parameter includedPrimaryTypes
, um die Ergebnisse auf Orte des Typs "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 Elemente eines unerwünschten Typs enthalten, z. B. "athletic_field"
.
Abfragevorhersagen anfordern
Abfragevorhersagen werden standardmäßig nicht zurückgegeben. Verwenden Sie den Anfrageparameter includeQueryPredictions
, um der Antwort Abfragevorhersagen 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 Vorschläge für Orte als auch für Suchanfragen, wie oben unter Informationen zur Antwort gezeigt. Jede Abfragevorhersage enthält das Feld text
mit einem empfohlenen Textsuchstring. Sie können eine Text Search (New)-Anfrage stellen, um weitere Informationen zu allen zurückgegebenen Abfragevorhersagen zu erhalten.
Ursprung verwenden
Nehmen Sie in diesem Beispiel origin
als Breiten- und Längengrad in die Anfrage auf.
Wenn Sie origin
angeben, schließt die API das Feld distanceMeters
in die Antwort ein, die die Luftentfernung zwischen origin
und dem Ziel enthält.
In diesem Beispiel wird als Ursprung das Zentrum San Franciscos 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 } } ] }