Usługa autouzupełniania (nowa) to usługa internetowa, która w odpowiedzi na żądanie HTTP zwraca prognozy miejsc i zapytań. W żądaniu określ wyszukiwany tekst i granice geograficzne, które sterują obszarem wyszukiwania.
Usługa autouzupełniania (nowa) może uwzględniać pełne słowa i podłańcuchy danych wejściowych oraz rozpoznawać nazwy miejsc, adresy i kody plus. Aplikacje mogą więc wysyłać zapytania w trakcie wpisywania zapytań przez użytkownika, aby na bieżąco zapewniać prognozy dotyczące miejsc i zapytań.
Odpowiedź z nowego interfejsu API autouzupełniania może zawierać 2 typy podpowiedzi:
- Podpowiedzi miejsc: miejsca, takie jak firmy, adresy i ciekawe miejsca, na podstawie podanego ciągu tekstowego i obszaru wyszukiwania. Prognozy dotyczące miejsc są domyślnie zwracane.
- Prognozy zapytania: ciągi zapytań pasujące do wejściowego ciągu tekstowego i obszaru wyszukiwania. Prognozy zapytań nie są domyślnie zwracane. Użyj parametru żądania
includeQueryPredictions
, aby dodać prognozy zapytań do odpowiedzi.
Na przykład wywołasz interfejs API, używając jako danych wejściowych ciągu zawierającego częściowe dane wejściowe użytkownika: „Sycylijski piz” z obszarem wyszukiwania ograniczonym do San Francisco w stanie Kalifornia. Odpowiedź zawiera wtedy listę przewidywanych miejsc, które pasują do ciągu wyszukiwania i obszaru wyszukiwania, np. restauracji o nazwie „Sycylijska pizza gastronomiczna”, a także szczegółowe informacje o danym miejscu.
Zwracane prognozy dotyczące miejsc mają zostać przedstawione użytkownikowi, aby pomóc mu w wyborze odpowiedniego miejsca. Możesz wysłać żądanie Szczegóły miejsca (nowe), aby uzyskać więcej informacji o dowolnych zwróconych prognozach dotyczących miejsc.
Odpowiedź może też zawierać listę podpowiedzi zapytania, które pasują do ciągu wyszukiwania i obszaru wyszukiwania, na przykład „Sycylijska pizza i makarony”. Każda prognoza zapytania w odpowiedzi zawiera pole text
z zalecanym ciągiem wyszukiwania. Wpisz ten ciąg znaków jako dane wejściowe funkcji Wyszukiwanie tekstowe (nowe), aby przeprowadzić bardziej szczegółowe wyszukiwanie.
API Explorer umożliwia wysyłanie żądań na żywo, dzięki czemu zapoznaj się z interfejsem API i jego opcjami:
WypróbujŻądania autouzupełniania (nowe)
Nowe (nowe) żądanie autouzupełniania to żądanie HTTP POST wysyłane do adresu URL w postaci:
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
Informacje o odpowiedzi
Autouzupełnianie (nowe) zwraca w odpowiedzi obiekt JSON. W odpowiedzi:
- Tablica
suggestions
zawiera wszystkie prognozowane miejsca i zapytania uporządkowane według ich postrzeganej trafności. Każde miejsce jest reprezentowane przez poleplacePrediction
, a każde zapytanie jest reprezentowane 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 następujący 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 }] }, ... } ...] }
Wymagane parametry
-
dane wejściowe
Ciąg tekstowy, który ma być przeszukiwany. Określ pełne słowa i podłańcuchy, nazwy miejsc, adresy i kody plus. Usługa autouzupełniania (nowa) zwraca dopasowania kandydatów na podstawie tego ciągu znaków i porządkuje wyniki na podstawie ich postrzeganej trafności.
Parametry opcjonalne
-
includedPrimaryTypes
Miejsce może mieć tylko jeden typ podstawowy spośród typów wymienionych w tabeli A lub tabeli B. Typem głównym może być np.
"mexican_restaurant"
lub"steak_house"
.Domyślnie interfejs API zwraca wszystkie miejsca na podstawie parametru
input
, niezależnie od podstawowej wartości typu powiązanej z miejscem. Ogranicz wyniki do określonego typu podstawowego lub podstawowego, przekazując parametrincludedPrimaryTypes
.Za pomocą tego parametru możesz określić maksymalnie 5 wartości typów z tabeli A lub tabeli B. Miejsce musi pasować do jednej z określonych wartości typu podstawowego, aby zostało uwzględnione w odpowiedzi.
Ten parametr może też zawierać wartość
(regions)
lub(cities)
. Kolekcja typu(regions)
filtruje obszary lub okręgi, np. dzielnice i kody pocztowe. Zbiór typu(cities)
filtruje miejsca, które Google identyfikuje jako miasto.Żądanie zostanie odrzucone z powodu błędu
INVALID_REQUEST
, jeśli:- Określono więcej niż 5 typów.
- Oprócz
(cities)
i(regions)
jest określony każdy typ. - Wszystkie nierozpoznane typy są określone.
-
includeQueryPredictions
Jeśli parametr ma wartość
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ędniaj tylko wyniki z listy określonych regionów określonej w postaci tablicy zawierającej maksymalnie 15 dwuznakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli go pominiesz, do odpowiedzi nie będą stosowane żadne ograniczenia. Aby na przykład ograniczyć regiony do Niemiec i Francji:
"includedRegionCodes": ["de", "fr"]
Jeśli podasz zarówno
locationRestriction
, jak iincludedRegionCodes
, wyniki będą znajdować się w obszarze przecięcia tych ustawień. -
inputOffset
Przesunięcie znaków Unicode liczone od zera, które wskazuje pozycję kursora w polu
input
. Pozycja kursora może wpływać na wyświetlane podpowiedzi. Jeśli pole jest puste, domyślna długość toinput
. -
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 polu
input
różni się od wartości określonej w polulanguageCode
lub jeśli zwrócone miejsce 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 tych wartości, 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 zestaw wyników zwracanych przez interfejs API oraz na kolejność, w jakiej są one zwracane. Dotyczy to również możliwości poprawiania błędów pisowni przez interfejs API.
-
Interfejs API stara się dostarczyć adres, który jest czytelny dla użytkownika i populacji lokalnej, i jednocześnie odzwierciedla dane wejściowe użytkownika. Prognozy miejsc są formatowane w różny sposób w zależności od danych wejściowych użytkownika w każdym żądaniu.
-
Jako pierwsze są wybierane pasujące hasła w parametrze
input
– nazwy zgodne z ustawieniami języka wskazanym w parametrzelanguageCode
(jeśli są dostępne). W przeciwnym razie używane są nazwy, które najlepiej pasują do danych wejściowych użytkownika. -
Adresy są sformatowane w języku lokalnym za pomocą skryptu, który w miarę możliwości jest czytelny dla użytkownika, dopiero po wybraniu pasujących haseł, które pasują do haseł w parametrze
input
. -
Pozostałe adresy są zwracane w preferowanym języku po wybraniu pasujących haseł zgodnie z hasłami w parametrze
input
. Jeśli nazwa nie jest dostępna w preferowanym języku, interfejs API używa najbliższego dopasowania.
-
Jako pierwsze są wybierane pasujące hasła w parametrze
Promowanie lokalizacji lub ograniczenie związane z lokalizacją
Aby zdefiniować obszar wyszukiwania, możesz podać
locationBias
lublocationRestriction
, ale nie obie te wartości. PolelocationRestriction
określa region, w którym muszą się znajdować wyniki, alocationBias
określa region, w którym wyniki muszą znajdować się w pobliżu, ale mogą znajdować się poza tym obszarem.locationBias
Określa obszar wyszukiwania. Ta lokalizacja działa jako odchylenie, 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 będą zwracane.
Określ obszar
locationBias
lublocationRestriction
w formie prostokątnego widocznego obszaru lub okręgu.Okrąg jest wyznaczany przez punkt środkowy i promień w metrach. Promień musi mieścić się w zakresie od 0,0 do 50 000,0 włącznie. Wartością domyślną jest 0,0. W przypadku
locationRestriction
ustaw promień 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 o długości i szerokości geograficznej przedstawiony jako dwa przeciwległe punkty
low
i dwóch punktów po przekątnej. Widoczny obszar jest uważany za obszar zamknięty, co oznacza, że obejmuje swoją granicę. Granice szerokości geograficznej muszą mieścić się w przedziale od -90 do 90 stopni włącznie, a granice długości geograficznej 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 geograficznej 180 stopni). - Jeśli
low.longitude
= –180 stopni, ahigh.longitude
= 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne. - Jeśli
low.longitude
= 180 stopni, ahigh.longitude
= -180 stopni, zakres długości geograficznej jest pusty.
Zarówno pole
low
, jak ihigh
muszą być wypełnione, a reprezentowane pole nie może być puste. Gdy to zrobisz, pojawi się błąd.Na przykład ten widoczny obszar w całości 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 oblicza się odległość prostą do miejsca docelowego (zwracany jako
distanceMeters
). Jeśli ta wartość zostanie pominięta, odległość prosta nie zostanie zwrócona. Wartość należy podać jako szerokość i długość geograficzną:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowa wartość ccTLD („domeny najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Wielka Brytania i Irlandia Północna”).
Jeśli podasz nieprawidłowy kod regionu, interfejs API zwróci błąd
INVALID_ARGUMENT
. Ten parametr może wpływać na wyniki w zależności od obowiązującego prawa. -
sessionToken
Tokeny sesji to ciągi wygenerowane przez użytkownika, które śledzą nowe (nowe) wywołania autouzupełniania jako „sesje”. Autouzupełnianie (nowość) korzysta z tokenów sesji, aby grupować etapy 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żywanie ograniczeń lokalizacji i uprzedzeń według lokalizacji
Do kontroli obszaru wyszukiwania interfejs API wykorzystuje domyślnie promowanie adresów IP. W przypadku promowania ze względu na adres IP interfejs API używa adresu IP urządzenia, aby wpływać na wyniki. Opcjonalnie do określenia obszaru wyszukiwania możesz użyć właściwości locationRestriction
lub locationBias
, ale nie obu naraz.
locationRestriction
określa obszar do przeszukania. Wyniki spoza określonego obszaru nie są zwracane. W poniższym przykładzie za pomocą polecenia locationRestriction
ograniczysz żą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 są zawarte 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 polu locationBias
lokalizacja działa jako odchylenie, co oznacza, że mogą być zwracane wyniki dotyczące wskazanej lokalizacji, w tym wyniki spoza określonego obszaru. W następnym przykładzie zmienisz żądanie tak, aby używało 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żyj uwzględnionych podstawowych typów
Użyj parametru includedPrimaryTypes
, aby określić maksymalnie 5 wartości typów z tabeli A, tabeli B, tylko (regions)
lub tylko (cities)
. Miejsce musi pasować do jednej z określonych wartości typu podstawowego, aby można było uwzględnić je w odpowiedzi.
W poniższym przykładzie określasz ciąg input
„Piłka nożna” i użyjesz parametru includedPrimaryTypes
, aby ograniczyć wyniki do firm 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ć informacje o niepożądanym typie, np. "athletic_field"
.
Żądanie prognoz zapytań
Prognozy zapytań nie są domyślnie zwracane. Użyj parametru żądania includeQueryPredictions
, aby dodać prognozy zapytania do odpowiedzi. 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 dotyczące miejsc, jak i prognozy zapytań, jak 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 wysłać żądanie Wyszukiwanie tekstowe (nowe), aby uzyskać więcej informacji o dowolnym ze zwróconych prognoz zapytań.
Użyj punktu początkowego
W tym przykładzie uwzględnij w żądaniu parametr origin
jako szerokość i długość geograficzną.
Jeśli dodasz parametr origin
, interfejs API uwzględni w odpowiedzi pole distanceMeters
, które zawiera prostą odległość od miejsca docelowego (origin
) do miejsca docelowego.
W tym przykładzie punkt początkowy jest ustawiony na 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 } } ] }
Wypróbuj
API Explorer umożliwia wykonywanie przykładowych żądań, aby zapoznać się z interfejsem API i jego opcjami.
- Wybierz ikonę interfejsu API () po prawej stronie.
- Opcjonalnie rozwiń sekcję Pokaż parametry standardowe i ustaw parametr
fields
na maskę pola. - Opcjonalnie edytuj Treść żądania.
- Kliknij przycisk Wykonaj. W wyskakującym okienku wybierz konto, z którego chcesz przesłać prośbę.
W panelu API Explorer kliknij ikonę rozwijania , aby rozwinąć okno API Explorer.