Der Dienst „Autocomplete (New)“ ist ein Webdienst, der als Antwort auf eine HTTP-Anfrage Ortsvorhersagen und Abfragevorhersagen zurückgibt. Geben Sie in der Anfrage einen Textsuchstring und geografische Grenzen an, die den Suchbereich steuern.
Der Dienst „Autocomplete (New)“ sucht nach vollständigen Wörtern und Teilstrings der Eingabe und kann so Ortsnamen, Adressen und Plus Codes auflösen. Anwendungen können Abfragen senden, während der Nutzer tippt, um spontan Vorschläge für Orte und Abfragen 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 Eingabetextstring und dem Suchbereich. Vervollständigungen von Orten werden standardmäßig zurückgegeben.
- Vervollständigungen von Suchanfragen: Abfragestrings, die mit dem eingegebenen Textstring und dem Suchbereich übereinstimmen. Vervollständigungen von Suchanfragen werden nicht standardmäßig 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 Teileingabe des Nutzers "Sicilian piz" enthält, wobei der Suchbereich auf San Francisco beschränkt ist. Die Antwort enthält dann eine Liste von Ortsvorschlägen, die mit dem Suchstring und dem Suchbereich übereinstimmen, z. B. das Restaurant mit dem Namen „Sicilian Pizza Kitchen“, sowie Details zum Ort.
Die zurückgegebenen Ortsvorschläge sollen dem Nutzer angezeigt werden, um ihn bei der Auswahl des gewünschten Ortes zu unterstützen. Mit der Anfrage Place Details (New) können Sie weitere Informationen zu zurückgegebenen Orten erhalten.
Die Antwort kann auch eine Liste von Vervollständigungen für die Suchanfrage enthalten, die mit dem Suchstring und dem Suchbereich übereinstimmen, z. B. "Sizilianische Pizza & Pasta". Jede Vorhersageanfrage 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.
Mit dem API Explorer können Sie Live-Anfragen stellen, damit Sie sich mit der API und den API-Optionen vertraut machen können:
Testen!Autocomplete (New)-Anfragen
Eine Autocomplete (New)-Anfrage ist eine HTTP POST-Anfrage an eine URL in folgendem Format:
https://places.googleapis.com/v1/places:autocomplete
Übergeben Sie alle Parameter im JSON-Anfragetext oder in den 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
Informationen zur Antwort
„Autocomplete (New)“ gibt ein JSON-Objekt als Antwort zurück. In der Antwort:
- Das Array
suggestions
enthält alle vorhergesagten Orte und Suchanfragen der Reihenfolge nach erkannter Relevanz. Jeder Ort wird durch einplacePrediction
-Feld und jede Abfrage durch einqueryPrediction
-Feld dargestellt. - Das Feld
placePrediction
enthält detaillierte Informationen zu einer einzelnen Vervollständigung eines Orts, einschließlich der Orts-ID und einer Textbeschreibung. - Das Feld
queryPrediction
enthält detaillierte Informationen zu einer einzelnen Vorhersage einer Abfrage.
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 ordnet die Ergebnisse nach erkannter Relevanz.
Optionale Parameter
-
includedPrimaryTypes
Ein Ort kann nur einen einzelnen primären Typ aus den in Tabelle A oder Tabelle B aufgeführten Typen 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 Wert des primären Typs, der dem Ort zugeordnet ist. Schränken Sie die Ergebnisse auf einen bestimmten primären Typ oder primäre Typen ein, indem Sie den ParameterincludedPrimaryTypes
übergeben.Verwenden Sie diesen Parameter, um bis zu fünf Typwerte aus Tabelle A oder Tabelle B anzugeben. Ein Ort muss mit einem der angegebenen Werte des primären Typs übereinstimmen, um in die Antwort aufgenommen zu werden.
Dieser Parameter kann stattdessen auch
(regions)
oder(cities)
enthalten. Die Sammlungsfilter des Typs(regions)
filtern für Gebiete oder Abteilungen wie Stadtteile und Postleitzahlen. Die Typensammlung(cities)
filtert nach Orten, die Google als Stadt identifiziert.In folgenden Fällen wird die Anfrage mit dem Fehler
INVALID_REQUEST
abgelehnt:- Es sind mehr als fünf Typen angegeben.
- Zusätzlich zu
(cities)
oder(regions)
wird jeder Typ angegeben. - Alle nicht erkannten Typen wurden angegeben.
-
includeQueryPredictions
Wenn
true
, enthält die Antwort sowohl Orts- als auch Abfragevorhersagen. Der Standardwert istfalse
, was bedeutet, dass die Antwort nur Ortsvorschläge enthält. -
includedRegionCodes
Schließt nur Ergebnisse aus der Liste der angegebenen Regionen ein, angegeben als Array mit bis zu 15 zweistelligen ccTLD-Werten ("top-level domain"). Wenn keine Angabe gemacht 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änge voninput
verwendet. -
languageCode
Die bevorzugte Sprache, in der Ergebnisse zurückgegeben werden sollen. Die Ergebnisse können in gemischten Sprachen vorliegen, wenn sich die in
input
verwendete Sprache von dem inlanguageCode
angegebenen Wert unterscheidet oder der zurückgegebene Ort keine Übersetzung von der lokalen Sprache inlanguageCode
hat.- Zur Angabe der bevorzugten Sprache musst du IETF BCP-47-Sprachcodes verwenden.
-
Wenn
languageCode
nicht angegeben ist, verwendet die API den imAccept-Language
-Header angegebenen Wert. Wenn keins von beiden angegeben ist, wird der Standardwerten
verwendet. 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, und auf die Reihenfolge, in der sie zurückgegeben werden. Dies beeinträchtigt auch die Fähigkeit der API, Rechtschreibfehler zu korrigieren.
-
Die API versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für die örtliche Bevölkerung lesbar ist und gleichzeitig die Nutzereingabe widerspiegelt. Vervollständigungen von Orten werden je nach Nutzereingabe in den einzelnen Anfragen unterschiedlich formatiert.
-
Übereinstimmende Begriffe im
input
-Parameter werden zuerst ausgewählt. Dabei werden Namen verwendet, die der durch denlanguageCode
-Parameter angegebenen Spracheinstellung entsprechen, sofern verfügbar. Andernfalls werden die Namen verwendet, die am besten mit der Nutzereingabe übereinstimmen. -
Adressen werden in der Landessprache und nach Möglichkeit in einem für den Nutzer lesbaren Script formatiert, wenn übereinstimmende Begriffe mit denen im
input
-Parameter übereinstimmen. -
Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben, nachdem übereinstimmende Begriffe mit den Begriffen im
input
-Parameter übereinstimmen. Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die am besten passende Übereinstimmung.
-
Übereinstimmende Begriffe im
„locationBias“ oder „locationRestriction“
Sie können
locationBias
oderlocationRestriction
angeben, aber nicht beides, um den Suchbereich zu definieren. Stellen Sie sichlocationRestriction
vor, um die Region anzugeben, in der sich die Ergebnisse befinden müssen, undlocationBias
die Region, in der sich die Ergebnisse befinden müssen, aber außerhalb des Bereichs sein können.locationBias
Gibt das Gebiet an, in dem gesucht werden soll. Dieser Standort dient als Verzerrung, d. h., Ergebnisse um den angegebenen Standort herum können zurückgegeben werden, auch solche außerhalb des angegebenen Bereichs.
locationRestriction
Gibt das Gebiet an, in dem gesucht werden soll. 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 einen Mittelpunkt und einen Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50.000,0 (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. Andernfalls 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 mit Breiten- und Längengrad, der als zwei diagonal gegenüberliegende
low
und hohe Punkte dargestellt wird. Ein Darstellungsbereich gilt als geschlossener Bereich, d. h. er umfasst seine Begrenzung. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad und die Längengradgrenzen zwischen -180 und 180 Grad liegen.- Wenn
low
=high
, besteht der Darstellungsbereich aus diesem einzelnen Punkt. - Wenn
low.longitude
>high.longitude
ist, wird der Längengradbereich umgekehrt (der Darstellungsbereich kreuzt die 180-Grad-Längenlinie). - 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 schließt beispielsweise New York City vollständig ein:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Wenn
-
Ursprung
Der Startpunkt, von dem aus die lineare Entfernung zum Ziel berechnet werden soll (zurückgegeben als
distanceMeters
). Wenn dieser Wert weggelassen wird, wird die direkte Entfernung nicht zurückgegeben. Muss als 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. So lautet beispielsweise die ccTLD des Vereinigten Königreichs „uk“ (.co.uk) und der ISO 3166-1-Code „gb“ (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äß geltendem Recht auf Ergebnisse auswirken. -
sessionToken
Sitzungstokens sind vom Nutzer erstellte Strings, die Aufrufe der automatischen Vervollständigung (Neu) als „Sitzungen“ erfassen. „Autocomplete (New)“ verwendet Sitzungstokens, um die Abfrage- und Auswahlphasen einer Nutzersuche mit automatischer Vervollständigung zu Abrechnungszwecken in einer separaten Sitzung zu gruppieren. Weitere Informationen finden Sie unter Sitzungstokens.
Beispiele für Autocomplete (New)
„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 zur Gewichtung der Ergebnisse. Sie können optional locationRestriction
oder locationBias
verwenden, aber nicht beides, um einen Bereich anzugeben, in dem gesucht werden soll.
locationRestriction
gibt das Gebiet 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 begrenzen, der auf 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 aus den angegebenen Bereichen 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 Verzerrung, sodass Ergebnisse um den angegebenen Ort herum zurückgegeben werden können, auch solche außerhalb des angegebenen Bereichs. Im nächsten Beispiel ändern Sie die Anfrage in locationBias
:
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, darunter auch Ergebnisse außerhalb des Umkreises 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" ] } }, ... ] }
„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 Werte des primären Typs übereinstimmen, um in die Antwort aufgenommen zu werden.
Im folgenden Beispiel geben Sie einen input
-String von "Soccer" an und verwenden den Parameter includedPrimaryTypes
, um Ergebnisse auf Einrichtungen 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 Ergebnisse eines unerwünschten Typs enthalten, z. B. "athletic_field"
.
Abfragevorhersagen anfordern
Vervollständigungen von Suchanfragen werden nicht standardmäßig 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 Orts- als auch Abfragevervollständigungen, wie oben unter Informationen zur Antwort dargestellt. Jede Vorhersageanfrage enthält das Feld text
mit einem empfohlenen Textsuchstring. Mit einer Text Search (New)-Anfrage können Sie weitere Informationen zu den zurückgegebenen Abfragevorhersagen abrufen.
Ursprung verwenden
Fügen Sie in diesem Beispiel origin
als Breiten- und Längengrad in die Anfrage ein.
Wenn Sie origin
angeben, schließt die API das Feld distanceMeters
in die Antwort ein, das die direkte Entfernung von origin
zum Ziel enthält.
In diesem Beispiel wird als Startpunkt 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 } } ] }
Jetzt testen
Mit dem API Explorer können Sie Beispielanfragen stellen, um sich mit der API und den API-Optionen vertraut zu machen.
- Wählen Sie rechts auf der Seite das API-Symbol aus.
- Erweitern Sie optional Standardparameter anzeigen und legen Sie den Parameter
fields
auf die Feldmaske fest. - Optional können Sie den Anfragetext bearbeiten.
- Klicken Sie auf die Schaltfläche Execute (Ausführen). Wählen Sie im Pop-up-Fenster das Konto aus, das Sie für die Anfrage verwenden möchten.
Klicken Sie im Bereich „API Explorer“ auf das Symbol zum Maximieren (), um das API Explorer-Fenster zu maximieren.