„Autocomplete (New)“ ist ein Webdienst, mit dem Vorhersagen und Abfragevorhersagen als Antwort auf eine HTTP-Anfrage. Geben Sie in der Anfrage einen Text Suchzeichenfolge und geografischen Grenzen, die den Suchbereich steuern.
Der Dienst „Autocomplete (New)“ sucht nach vollständigen Wörtern und Teilzeichenfolgen der Eingabe, die Ortsnamen, Adressen und Plus Codes. Anwendungen können daher Suchanfragen während der Nutzereingabe, um spontane Vervollständigungen für Orte und Suchanfragen bereitzustellen.
Die Antwort der Autocomplete (New) API kann zwei Typen enthalten der Vervollständigungen:
- Vervollständigungen von Orten: Orte wie Unternehmen, Adressen und Punkte basierend auf der angegebenen Textzeichenfolge und dem Suchbereich der Eingabe. Vervollständigungen von Orten sind werden standardmäßig zurückgegeben.
- Abfragevorhersagen: Abfragestrings, die mit dem eingegebenen Textstring übereinstimmen
Suchbereich. Vervollständigungen von Suchanfragen werden nicht standardmäßig zurückgegeben. Verwenden Sie die Methode
includeQueryPredictions
-Anfrageparameter, um Abfragevorhersagen zum Antwort.
Beispiel: Sie rufen die API mit einem String auf, der eine teilweise Nutzereingabe enthält, „Sizilianische piz“, wobei der Suchbereich auf San Francisco beschränkt ist. Die Antwort enthält dann ein Liste von Vervollständigungen für Orte, die mit dem Suchstring und dem Suchbereich übereinstimmen, z. B. Restaurant namens „Sizilianische Pizzaküche“ sowie Details zum jeweiligen Ort.
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 eine Place Details (neu) , um weitere Informationen zu den zurückgegebenen Ortsvorschlägen zu erhalten.
Die Antwort kann auch eine Liste mit Vorhersagen der Suchanfrage enthalten, die dem
Suchzeichenfolge und Suchbereich, wie z. B. "Sizilianische Pizza & Pasta“. Jede Vorhersageanfrage in der
Antwort das Feld text
mit einem empfohlenen Textsuchstring enthält. Verwenden
als Eingabe für
Textsuche (neu)
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:
Testen!Autocomplete (New)-Anfragen
Eine Autocomplete (New)-Anfrage ist eine HTTP POST-Anfrage an eine URL in das Formular:
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 Reihe nach basierend auf ihrer wahrgenommenen Relevanz. Jeder Ort wird durch einplacePrediction
und jede Abfrage wird dargestellt. durch einqueryPrediction
-Feld. - Das Feld
placePrediction
enthält detaillierte Informationen zu einem einzelnen Ortsvervollständigung, einschließlich Orts-ID und Textbeschreibung. - Das Feld
queryPrediction
enthält detaillierte Informationen zu einem 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 Teilzeichenfolgen an, Ortsnamen, Adressen und Plus Codes. „Autocomplete (New)“-Dienst gibt mögliche Übereinstimmungen basierend auf diesem String zurück und ordnet die Ergebnisse basierend auf ihre wahrgenommene Relevanz.
Optionale Parameter
-
includedPrimaryTypes
Ein Ort kann nur einen einzigen primären Typ aus den Typen haben, die in Tabelle A oder Tabelle B. Beispiel: kann der primäre Typ
"mexican_restaurant"
oder"steak_house"
sein.Standardmäßig gibt die API alle Orte basierend auf dem Parameter
input
zurück, unabhängig davon, des mit dem Ort verknüpften primären Typwerts. Ergebnisse auf einen bestimmten Wert beschränken primären Typ oder primären Typen durch Übergeben desincludedPrimaryTypes
-ParametersVerwenden Sie diesen Parameter, um bis zu fünf Typwerte aus Tabelle A oder Tabelle B. Ein Ort muss stimmt mit einem der angegebenen Werte des primären Typs überein, die in die Antwort aufgenommen werden sollen.
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. Standardeinstellung Der Wert istfalse
, was bedeutet, dass die Antwort nur Ortsvorschläge enthält. -
includedRegionCodes
Nur Ergebnisse aus der Liste der angegebenen Regionen einschließen, angegeben als Array von bis zu 15 ccTLD („Top-Level-Domain“) aus zwei Zeichen bestehen. Wenn keine Angabe gemacht wird, werden keine Einschränkungen auf die Antwort angewendet. Beispiel: zur Beschränkung der 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 das Länge voninput
. -
languageCode
Die bevorzugte Sprache, in der Ergebnisse zurückgegeben werden sollen. Die Ergebnisse können in gemischten Sprachen vorliegen Die in
input
verwendete Sprache unterscheidet sich von dem Wert, der durchlanguageCode
zurückgegeben oder der zurückgegebene Ort keine Übersetzung aus dem Sprache auflanguageCode
.- Sie müssen IETF verwenden. BCP-47-Sprachcodes zur Angabe der bevorzugten Sprache.
-
Ist
languageCode
nicht angegeben, verwendet die API den Wert, der in derAccept-Language
-Header. Wenn keins von beiden angegeben ist, wird der Standardwerten
Wenn Sie einen ungültigen Sprachcode angeben, gibt die API eineINVALID_ARGUMENT
Fehler. - Die bevorzugte Sprache hat einen geringen Einfluss auf die Suchergebnisse, und in welcher Reihenfolge 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
lokale Bevölkerung und spiegeln gleichzeitig die Nutzereingaben wider. Vervollständigungen von Orten sind
je nach Nutzereingabe in jeder Anfrage unterschiedlich formatiert.
-
Zuerst werden übereinstimmende Begriffe im Parameter
input
ausgewählt, wobei die Namen übereinstimmen mit der im ParameterlanguageCode
angegebenen Spracheinstellung, wenn verwenden, während Sie andernfalls die Namen verwenden, die am besten zur Nutzereingabe passen. -
Die Adressen sind in der Landessprache und in einem für den Nutzer lesbaren Script formatiert
wenn möglich, erst, nachdem übereinstimmende Begriffe so ausgewählt wurden, dass sie mit den Begriffen im
input
-Parameter. -
Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben, nachdem die übereinstimmenden Begriffe
Sie wurden so ausgewählt, dass sie den Begriffen im Parameter
input
entsprechen. Wenn ein Name nicht in der bevorzugten Sprache verfügbar ist, verwendet die API die genaueste Übereinstimmung.
-
Zuerst werden übereinstimmende Begriffe im Parameter
„locationBias“ oder „locationRestriction“
Sie können
locationBias
oderlocationRestriction
angeben. aber nicht beides, um den Suchbereich zu definieren. Stellen Sie sichlocationRestriction
vor, die Region, in der sich die Ergebnisse befinden müssen, undlocationBias
als Sie geben die Region an, in der sich die Ergebnisse befinden müssen, aber auch außerhalb liegen können in der Umgebung.locationBias
Gibt das Gebiet an, in dem gesucht werden soll. Dieser Standort dient als Verzerrung, können Ergebnisse im Umkreis des angegebenen Standorts zurückgegeben werden, einschließlich der Ergebnisse außerhalb des angegebenen Bereichs liegt.
locationRestriction
Gibt das Gebiet an, in dem gesucht werden soll. Ergebnisse außerhalb des angegebenen Bereichs werden nicht zurückgegeben.
Geben Sie die Region
locationBias
oderlocationRestriction
als rechteckigen Darstellungsbereich oder als Kreis.Ein Kreis wird durch einen Mittelpunkt und einen Radius in Metern definiert. Der Radius muss zwischen 0,0 und 50000,0 (einschließlich). 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.Beispiel:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Ein Rechteck ist der Darstellungsbereich mit Breiten- und Längengraden, diagonal gegenüberliegend
low
und hohen Punkten. Ein Darstellungsbereich wird als geschlossene Region, d. h., sie umfasst ihre Begrenzung. Die Breitengradgrenzen muss zwischen -90 und einschließlich 90 Grad liegen und die Längengrenzen muss zwischen -180 und 180 Grad liegen:- Wenn
low
=high
, 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 undhigh.longitude
= 180 Grad ist, enthält der Darstellungsbereich alle Längengrade. - Wenn
low.longitude
= 180 Grad undhigh.longitude
= -180 Grad, Längengradbereich ist 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
-
origin
Der Ursprungspunkt, von dem aus die direkte Entfernung zum Ziel (zurückgegeben als
distanceMeters
). Wenn dieser Wert gleich ausgelassen, wird keine geradlinige Entfernung zurückgegeben. Muss angegeben werden als Längen- und Breitengrade:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
Der Regionscode, der zum Formatieren der Antwort verwendet wird, angegeben als ccTLD („Top-Level-Domain“) aus zwei Zeichen bestehen. Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes, mit einigen nennenswerten 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 des Vereinigten Königreichs Großbritannien und Nordirland“).
Wenn Sie einen ungültigen Regionscode angeben, gibt die API ein
INVALID_ARGUMENT
zurück. Fehler. Der Parameter kann sich gemäß geltendem Recht auf Ergebnisse auswirken. -
sessionToken
Sitzungstokens sind vom Nutzer erstellte Strings, die die automatische Vervollständigung erfassen (Neu) Aufrufe als „Sitzungen“. Bei Autocomplete (New) werden Sitzungstokens verwendet, um Gruppieren Sie die Abfrage- und Auswahlphasen einer Nutzersuche mit automatischer Vervollständigung in einer separaten Sitzung Abrechnungszwecke. 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, um die Ergebnisse zu gewichten. Sie können optional
locationRestriction
oder locationBias
, aber nicht beides, um ein zu durchsuchendes Gebiet anzugeben.
locationRestriction
gibt das Gebiet an, in dem gesucht werden soll. Ergebnisse außerhalb des angegebenen Bereichs
nicht zurückgegeben. Im folgenden Beispiel verwenden Sie locationRestriction
, um den
-Anfrage für einen Kreis mit einem Radius von 5.000 Metern um San Francisco:
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, d. h. Ergebnisse um den
angegebenen Standort zurückgegeben werden können, auch Ergebnisse außerhalb des angegebenen Bereichs. Im nächsten
Beispiel: Sie ändern 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
Mit dem Parameter includedPrimaryTypes
können Sie bis zu fünf Typwerte aus der
Tabelle A,
Tabelle B,
oder nur (regions)
oder nur (cities)
. Ein Ort muss mit einem der angegebenen
Primärtypwerte, die in die Antwort aufgenommen werden sollen.
Im folgenden Beispiel geben Sie einen input
-String von
„Fußball“ und verwenden Sie den Parameter includedPrimaryTypes
, um die Ergebnisse auf
Einrichtungen des Typs "sporting_goods_store"
:
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 folgende Werte enthalten:
Einrichtungen eines bestimmten Typs, wie z. B. "athletic_field"
.
Abfragevorhersagen anfordern
Vervollständigungen von Suchanfragen werden nicht standardmäßig zurückgegeben. includeQueryPredictions
verwenden
-Anfrageparameter, um der Antwort Suchanfragenvorhersagen 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 Vorhersage bei Abfragen
enthält das Feld text
mit einem empfohlenen Textsuchstring. Sie können eine
Textsuche (neu)
, um weitere Informationen zu den zurückgegebenen Abfragevorhersagen zu erhalten.
Ursprung verwenden
Fügen Sie in diesem Beispiel origin
als Breiten- und Längengrad in die Anfrage ein.
Wenn Sie origin
einfügen, schließt die API das Feld distanceMeters
in die
Antwort, die die Luftlinie zwischen origin
und dem 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 } } ] }
Testen!
Mit dem API Explorer können Sie Beispielanfragen stellen, damit Sie sich mit der API und den API-Optionen vertraut machen können.
- Klicken Sie auf das API-Symbol . rechts auf der Seite.
- Erweitern Sie optional Standardparameter anzeigen und legen Sie
Parameter
fields
zur Feldmaske hinzu. - 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 API Explorer auf das Symbol zum Maximieren , um das API Explorer-Fenster zu maximieren.