Usługa autouzupełniania (nowa) to usługa internetowa, która zwraca prognozy miejsc i prognozy zapytań w odpowiedzi na żądanie HTTP. W żądaniu podaj ciąg tekstowy wyszukiwania i granice geograficzne, które kontrolują obszar wyszukiwania.
Usługa autouzupełniania (nowa) może dopasowywać pełne słowa i podłańcuchy danych wejściowych, rozpoznając nazwy miejsc, adresy i kody plus. Aplikacje mogą więc wysyłać zapytania w ramach typów użytkowników, aby dostarczać aktualne informacje o miejscach i zapytaniach.
Odpowiedź z interfejsu Autocomplete (New) API może zawierać 2 typy prognoz:
- Przewidywanie miejsc: miejsca, takie jak firmy, adresy i ciekawe miejsca, określone na podstawie podanego ciągu tekstowego i obszaru wyszukiwania. Prognozy dotyczące miejsc są zwracane domyślnie.
- Podpowiedzi zapytań: ciągi zapytań pasujące do wejściowego ciągu tekstowego i obszaru wyszukiwania. Prognozy zapytań nie są domyślnie zwracane. Aby dodać prognozy zapytań do odpowiedzi, użyj parametru żądania
includeQueryPredictions
.
Na przykład wywoływasz interfejs API, używając jako danych wejściowych ciągu, który zawiera część danych wejściowych użytkownika („piz sycylijski”) z obszarem wyszukiwania ograniczonym do San Francisco w Kalifornii. Odpowiedź zawiera listę podpowiedzi dotyczących miejsc, które pasują do wyszukiwanego hasła i obszaru wyszukiwania, np. restauracji „Pizzeria sycylijska” oraz szczegółowe informacje o miejscu.
Zwrócone prognozy dotyczące miejsc są wyświetlane użytkownikom, aby ułatwić im wybór odpowiedniego miejsca. Możesz wysłać żądanie Place Details (nowość), aby uzyskać więcej informacji o zwróconych prognozach miejsc.
Odpowiedź może też zawierać listę podpowiedzi zapytania, które pasują do wyszukiwanego ciągu i obszaru wyszukiwania, np. „Pizza sycylijska i makarony”. Każda prognoza zapytania w odpowiedzi zawiera pole text
zawierające zalecany ciąg znaków wyszukiwania. Użyj tego ciągu jako danych wejściowych do wyszukiwania (nowego), aby przeprowadzić bardziej szczegółowe wyszukiwanie.
Żądania autouzupełniania (nowe)
Żądanie autouzupełniania (nowe) to żądanie HTTP POST kierowane do adresu URL w tym formularzu:
https://places.googleapis.com/v1/places:autocomplete
Przekazuj wszystkie parametry w treści żądania JSON lub w nagłówkach w ramach żądania POST. Na przykład:
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
Przesyłanie prośby przy użyciu autouzupełniania (nowość)
Places API obsługuje istniejące interfejsy API autouzupełniania i autouzupełniania. Jeśli znasz te interfejsy API, nowa wersja testowa autouzupełniania wprowadza następujące zmiany:- Nowe autouzupełnianie korzysta z żądań POST HTTP. Przekazuj parametry w treści żądania lub w nagłówkach w ramach żądania POST HTTP. W przeciwieństwie do istniejących interfejsów API parametry adresu URL przekazujesz za pomocą żądania HTTP GET.
- Nowe autouzupełnianie obsługuje jako mechanizm uwierzytelniania zarówno klucze interfejsu API, jak i tokeny OAuth.
- Nowe autouzupełnianie obsługuje tylko format JSON jako format odpowiedzi.
W tabeli poniżej znajdziesz listę parametrów istniejących interfejsów API autouzupełniania i zapytań, które zostały zmienione lub zmodyfikowane pod kątem nowego autouzupełniania albo te, które nie są już obsługiwane.
Bieżący parametr | Nowy parametr | Uwagi |
---|---|---|
components |
includedRegionCodes |
|
language |
languageCode |
|
location |
locationBias |
|
ipbias |
Jeśli pominiesz zarówno locationBias , jak i locationRestriction , interfejs API używa domyślnie promowania ze względu na adres IP. |
|
offset |
inputOffset |
|
radius |
locationBias lub locationRestriction |
|
region |
regionCode |
|
stricbounds |
locationRestriction |
|
sessiontoken |
sessionToken |
|
types |
includedPrimaryTypes |
Limity wykorzystania
W wersji przedpremierowej możesz utworzyć maksymalnie 600 zapytań na minutę na projekt.
Opcje pomocy dotyczące wersji przedpremierowych
Google nie ma obowiązku zapewnienia pomocy w zakresie wersji przedpremierowych, funkcji ani funkcji Usług, jednak prośby na takich etapach rozpatrujemy indywidualnie.
- Wersje przedpremierowe nie są objęte gwarancją jakości usług Google Maps Platform.
- Zalecamy użycie mechanizmów zastępczych, zwłaszcza jeśli używasz wersji przedpremierowej w środowisku produkcyjnym. Przykłady sytuacji awaryjnych to: przekroczenie limitu, nieoczekiwane kody odpowiedzi i czas oczekiwania lub nieoczekiwane odpowiedzi w porównaniu z istniejącym autouzupełnianiem.
Możesz z niego korzystać, aby prosić o nowe funkcje lub sugerować modyfikacje dotychczasowych. Opisz konkretną funkcję, którą powinniśmy dodać, i podaj powód, dla którego uważasz, że jest ona ważna. Jeśli to możliwe, podaj szczegółowe informacje o swoim przypadku użycia i nowych możliwościach, jakie daje ta funkcja:
Jeśli masz inne pytania dotyczące funkcji, wyślij e-maila na adres newplacesapi@google.com.
Informacje o odpowiedzi
Autouzupełnianie (nowe) zwraca w odpowiedzi obiekt JSON. W odpowiedzi:
- Tablica
suggestions
zawiera wszystkie przewidywane miejsca i zapytania w kolejności na podstawie ich postrzeganej trafności. Każde miejsce jest reprezentowane przez poleplacePrediction
, a każde zapytanie – przez polequeryPrediction
. - Pole
placePrediction
zawiera szczegółowe informacje o prognozie dotyczącej pojedynczego miejsca, w tym identyfikator miejsca i opis tekstowy. - Pole
queryPrediction
zawiera szczegółowe informacje o prognozie pojedynczego zapytania.
Pełny obiekt JSON ma postać:
{ "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 }] }, ... } ...] }
Wymagane parametry
-
dane wejściowe
Ciąg tekstowy służący do wyszukiwania. Podaj pełne słowa i podłańcuchy, nazwy miejsc, adresy i kody plus. Usługa autouzupełniania (nowa) zwraca kandydujące dopasowania na podstawie tego ciągu i porządkuje wyniki na podstawie ich postrzeganej trafności.
Parametry opcjonalne
-
includedPrimaryTypes
Miejsce może mieć tylko jeden typ podstawowy z powiązanych z nim typów tabeli A lub tabeli B. Typem podstawowym może być na przykład
"mexican_restaurant"
lub"steak_house"
.Domyślnie interfejs API zwraca wszystkie miejsca na podstawie parametru
input
, niezależnie od wartości typu podstawowego powiązanego z danym miejscem. Możesz ograniczyć wyniki do określonego typu głównego, przekazując parametrincludedPrimaryTypes
.Za pomocą tego parametru możesz określić maksymalnie 5 wartości typu z tabeli A lub tabeli B. Aby miejsce zostało uwzględnione w odpowiedzi, musi pasować do jednej z określonych wartości typu podstawowego.
Żądanie zostało odrzucone z błędem
INVALID_REQUEST
, jeśli:- Określono więcej niż 5 typów.
- Podano nierozpoznane typy.
-
includeQueryPredictions
Jeśli
true
, odpowiedź zawiera zarówno prognozy dotyczące miejsc, jak i zapytań. Wartość domyślna tofalse
, co oznacza, że odpowiedź zawiera tylko prognozy dotyczące miejsc. -
includedRegionCodes
Uwzględnij tylko wyniki z listy określonych regionów, określonej w postaci tablicy zawierającej maksymalnie 15 dwuliterowych wartości ccTLD („domena najwyższego poziomu”). Jeśli zostanie pominięty, do odpowiedzi nie zostaną zastosowane żadne ograniczenia. Aby np. ograniczyć regiony do Niemiec i Francji:
"includedRegionCodes": ["de", "fr"]
Jeśli podasz zarówno zasady
locationRestriction
, jak iincludedRegionCodes
, wyniki pojawią się w obszarze przecięcia tych 2 ustawień. -
inputOffset
Przesunięcie znaku Unicode liczone od zera wskazujące pozycję kursora w
input
. Położenie kursora może mieć wpływ na zwracane prognozy. Jeśli pole jest puste, domyślnie przyjmuje długośćinput
. -
languageCode
Preferowany język, w którym mają być zwracane wyniki. Wyniki mogą być w różnych językach, jeśli język używany w zasadzie
input
jest inny niż wartość określona przez atrybutlanguageCode
lub jeśli dla zwracanego miejsca nie ma tłumaczenia z języka lokalnego nalanguageCode
.- Aby określić preferowany język, musisz użyć kodów języka IETF BCP-47.
-
Jeśli nie podano
languageCode
, interfejs API używa wartości podanej w nagłówkuAccept-Language
. Jeśli nie podasz żadnej z nich, wartość domyślna toen
. Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błądINVALID_ARGUMENT
. - Preferowany język ma niewielki wpływ na zbiór wyników, które interfejs API wybiera do zwrócenia, oraz na kolejność ich zwracania. Wpływa to również na możliwość poprawiania błędów pisowni przez interfejs API.
-
Interfejs API stara się podać adres, który jest czytelny zarówno dla użytkownika, jak i lokalnej populacji, a jednocześnie odzwierciedla dane wejściowe użytkownika. Prognozy dotyczące miejsc są formatowane w różny sposób w zależności od danych wejściowych użytkownika w każdym żądaniu.
-
Pasujące hasła w parametrze
input
są wybierane jako pierwsze z nazwami zgodnymi z preferencjami językowymi określonymi w parametrzelanguageCode
(jeśli są dostępne) lub w innych przypadkach z nazwami najlepiej pasującymi do danych wejściowych użytkownika. -
Adresy są formatowane w języku lokalnym, w miarę możliwości przy użyciu skryptu zrozumiałego dla użytkownika pod warunkiem, że pasujące hasła pasują do haseł w parametrze
input
. -
Wszystkie inne adresy są zwracane w preferowanym języku, gdy pasujące hasła pasują do haseł w parametrze
input
. Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API używa najbliższego dopasowania.
-
Pasujące hasła w parametrze
locationBias lub ograniczenie lokalizacji
Aby określić obszar wyszukiwania, możesz użyć właściwości
locationBias
lublocationRestriction
, ale nie obu naraz.locationRestriction
to raczej region, w którym powinny znajdować się wyniki, alocationBias
– region, w którym wyniki muszą znajdować się w pobliżu, ale mogą być poza tym obszarem.locationBias
Określa obszar wyszukiwania. Ta lokalizacja jest odchyleniem, co oznacza, że mogą być zwracane wyniki dotyczące określonej lokalizacji, w tym wyniki spoza określonego obszaru.
locationRestriction
Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane.
Określ region
locationBias
lublocationRestriction
jako prostokątny widoczny obszar lub okrąg.Okrąg jest określony przez punkt środkowy i promień w metrach. Promień musi mieścić się w zakresie od 0,0 do 50 000,0 włącznie. Wartość domyślna to 0,0. W przypadku właściwości
locationRestriction
promień musisz ustawić na wartość większą niż 0,0. W przeciwnym razie żądanie nie zwraca żadnych wyników.Na przykład:
"locationBias": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Prostokąt to widoczny obszar obejmujący szerokość i długość geograficzną wyrażony jako 2 położone na ukos kąty naprzeciwległe o boku
low
i najwyższego punktu. Widoczny obszar jest traktowany jako zamknięty obszar, co oznacza, że obejmuje swoją granicę. Granice szerokości geograficznej muszą mieścić się w zakresie od -90 do 90 stopni włącznie, a długość geograficzna – od -180 do 180 stopni włącznie:- Jeśli
low
=high
, widoczny obszar składa się z tego pojedynczego punktu. - Jeśli
low.longitude
>high.longitude
, zakres długości geograficznej jest odwrócony (widoczny obszar przecina linię długości 180 stopni). - Jeśli
low.longitude
= -180 stopni,high.longitude
= 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne. - Jeśli
low.longitude
= 180 stopni,high.longitude
= -180 stopni, zakres długości geograficznej jest pusty.
Musisz wypełnić zarówno pole
low
, jak ihigh
, a reprezentowane pole nie może być puste. Pusty widoczny obszar powoduje wystąpienie błędu.Na przykład ten widoczny obszar w pełni obejmuje Nowy Jork:
"locationBias": { "rectangle": { "low": { "latitude": 40.477398, "longitude": -74.259087 }, "high": { "latitude": 40.91618, "longitude": -73.70018 } } }
- Jeśli
-
pochodzenie
Punkt początkowy, z którego należy obliczyć odległość w linii prostej do miejsca docelowego (zwrócony jako
distanceMeters
). Jeśli pominiesz tę wartość, odległość w linii prostej nie zostanie zwrócona. Należy podać je jako współrzędne szerokości i długości geograficznej:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
Kod regionu użyty do sformatowania odpowiedzi, określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Większość kodów domen ccTLD jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD w Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie oznaczający jednostkę „Wielka Brytania i Irlandia Północna”).
Jeśli podasz nieprawidłowy kod regionu, interfejs API zwróci błąd
INVALID_ARGUMENT
. Parametr może wpływać na wyniki w zależności od obowiązującego prawa. -
sessionToken
Tokeny sesji to ciągi tekstowe generowane przez użytkownika, które śledzą (nowe) wywołania autouzupełniania jako „sesje”. Funkcja autouzupełniania (nowa) używa tokenów sesji do grupowania faz zapytania i wyboru autouzupełniania wyszukiwania użytkownika w oddzielną sesję na potrzeby rozliczeń. Więcej informacji znajdziesz w artykule o tokenach sesji.
Przykłady autouzupełniania (nowe)
Użyj ograniczeń lokalizacji i lokalizacji Biias
Do sterowania obszarem wyszukiwania interfejs API używa domyślnie promowania ze względu na adres IP. W przypadku promowania wyników ze względu na adres IP
interfejs API korzysta z adresu IP urządzenia. Opcjonalnie możesz określić obszar wyszukiwania, używając właściwości locationRestriction
lub locationBias
, ale nie obu naraz.
locationRestriction
określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W poniższym przykładzie użyjesz funkcji locationRestriction
, aby ograniczyć żądanie do okręgu o promieniu 5000 metrów wyśrodkowanym na 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
Wszystkie wyniki z określonych obszarów znajdują się w tablicy suggestions
:
{ "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" ] } } ] }
W przypadku funkcji locationBias
lokalizacja służy do odchyleń, co oznacza, że zwracane są wyniki dotyczące wskazanej lokalizacji, w tym wyniki spoza określonego obszaru. W następnym przykładzie zmieniasz żądanie, aby użyć 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
Wyniki zawierają teraz znacznie więcej elementów, w tym wyniki spoza promienia 5000 metrów:
{ "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" ] } }, ... ] }
Używaj uwzględnionych typów Podstawowych
Parametr includedPrimaryTypes
pozwala ograniczyć wyniki żądania do określonego typu, zgodnie z opisem w tabelach A i tabeli B. Możesz określić tablicę z maksymalnie 5 wartościami.
W przypadku jego pominięcia zwracane są wszystkie typy.
W poniższym przykładzie określisz ciąg input
„Piłka nożna” i użyjesz parametru includedPrimaryTypes
, aby ograniczyć wyniki do instytucji typu "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
Jeśli pominiesz parametr includedPrimaryTypes
, wyniki mogą zawierać instytucje typu, którego nie potrzebujesz, np. "athletic_field"
.
Wysyłanie żądań prognoz zapytań
Prognozy zapytań nie są domyślnie zwracane. Aby dodać prognozy zapytań do odpowiedzi, użyj parametru żądania includeQueryPredictions
. Na przykład:
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
Tablica suggestions
zawiera teraz zarówno prognozy miejsc, jak i prognozy zapytań, tak jak to pokazano powyżej w sekcji Informacje o odpowiedzi. Każda prognoza zapytania zawiera pole text
zawierające zalecany ciąg znaków wyszukiwania. Możesz utworzyć żądanie wyszukiwania tekstu (nowego), aby uzyskać więcej informacji o dowolnych zwróconych prognozach zapytań.
Użyj punktu początkowego
W tym przykładzie uwzględnij w żądaniu origin
jako szerokość i długość geograficzną.
Gdy uwzględnisz origin
, interfejs API umieszcza w odpowiedzi pole distanceMeters
, które zawiera odległość w linii prostej od miejsca origin
do miejsca docelowego.
Ten przykład ustawia początek lokalizacji w centrum San Francisco:
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
Odpowiedź zawiera teraz: 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 } } ] }