Usługa autouzupełniania (nowa) to usługa sieciowa, która zwraca miejsca w odpowiedzi na żądania HTTP. W żądaniu wpisz tekst ciąg znaków i granice geograficzne, które kontrolują obszar wyszukiwania.
Funkcja autouzupełniania (nowa) może uwzględniać pełne słowa oraz podłańcucha danych wejściowych, rozpoznawanie nazw miejsc, adresów i kodów plus. W związku z tym aplikacje mogą wysyłać zapytań wprowadzanych przez użytkownika, zapewniając błyskawiczne wyniki i prognozy zapytań.
Odpowiedź z interfejsu API autouzupełniania (nowego) może zawierać 2 typy prognoz:
- Przewidywane miejsca: miejsca, takie jak firmy, adresy i punkty. na podstawie podanego ciągu tekstowego i obszaru wyszukiwania. Prognozy miejsc są zwracanych domyślnie.
- Prognozy zapytań: ciągi zapytań pasujące do wejściowego ciągu tekstowego oraz
obszar wyszukiwania. Prognozy zapytań nie są domyślnie zwracane. Użyj
Parametr żądania
includeQueryPredictions
, który pozwala dodać prognozy zapytań do funkcji .
Na przykład wywołujesz interfejs API, używając jako danych wejściowych ciągu znaków zawierającego częściowe dane wejściowe użytkownika, „Pizza sycylijska” z obszarem wyszukiwania ograniczonych do San Francisco, Kalifornia. Odpowiedź zawiera wtedy listę przewidywanych miejsc, które pasują do wyszukiwanego ciągu i obszaru wyszukiwania, na przykład „Sycylijska pizza kulinarna” wraz z dodatkowymi informacjami o tym miejscu.
Zwrócone prognozy dotyczące miejsc mają zostać przedstawione użytkownikowi jako pomocne ich przy wyborze odpowiedniego miejsca. Możesz Szczegóły miejsca (nowe) żądania uzyskania dodatkowych informacji o dowolnym ze zwróconych prognoz dotyczących miejsc.
Odpowiedź może też zawierać listę prognoz zapytania, które pasują do zapytania
ciągu wyszukiwania i obszaru wyszukiwania, np. „Pizza sycylijska Makaron”. Każda prognoza zapytania w kolumnie
odpowiedź zawiera pole text
zawierające zalecany ciąg wyszukiwania tekstowego. Użyj
jako danych wejściowych w celu
Wyszukiwanie tekstowe (nowość)
aby przeprowadzić bardziej szczegółowe wyszukiwanie.
API Explorer umożliwia wysyłanie żądań na żywo, dzięki czemu możesz zapoznać się z interfejsem API Opcje interfejsu API:
WypróbujŻądania autouzupełniania (nowe)
Nowe (nowe) żądanie autouzupełniania to żądanie HTTP POST wysyłane do adresu URL w formularz:
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 w kolejności na podstawie ich postrzeganej trafności. Każde miejsce jest reprezentowane przez poleplacePrediction
i uwzględniane jest każde zapytanie polequeryPrediction
. - Pole
placePrediction
zawiera szczegółowe informacje o jednym przewidywane miejsce, w tym identyfikator miejsca i opis. - Pole
queryPrediction
zawiera szczegółowe informacje o jednym w prognozie 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ślać 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 i ustala kolejność wyników na podstawie ich postrzeganej trafności.
Parametry opcjonalne
-
includedPrimaryTypes
Miejsce może mieć tylko jeden typ główny spośród typów wymienionych w Tabela A lub Tabela B. Przykład: typ podstawowy to
"mexican_restaurant"
lub"steak_house"
.Domyślnie interfejs API zwraca wszystkie miejsca na podstawie parametru
input
, niezależnie od tego podstawowego typu powiązanego z miejscem. Ogranicz wyniki, aby miały określoną wartość podstawowych lub głównych, przekazując parametrincludedPrimaryTypes
.Za pomocą tego parametru możesz określić maksymalnie 5 wartości typów z tabeli A lub Tabela B. Miejsce musi pasują do jednej z określonych wartości typu podstawowego, które mają być 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ń. Domyślny wartość tofalse
, co oznacza, że odpowiedź zawiera tylko prognozy dotyczące miejsc. -
includedRegionCodes
Uwzględnij tylko wyniki z listy określonych regionów, określonej jako tablica do 15 znaków ccTLD („domena najwyższego poziomu”) dwuznakowych. Jeśli go pominiesz, do odpowiedzi nie będą stosowane żadne ograniczenia. Przykład: aby ograniczyć regiony do Niemiec i Francji:
"includedRegionCodes": ["de", "fr"]
Jeśli podasz zarówno
locationRestriction
, jak iincludedRegionCodes
, będą znajdować się w obszarze przecięcia obu 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 jest pusta, stosowana jest domyślna wartość o długościinput
. -
languageCode
Preferowany język, w którym mają być zwracane wyniki. Wyniki mogą być w różnych językach jeśli język użyty w
input
jest inny niż wartość określona przezlanguageCode
lub jeśli zwrócone miejsce nie ma tłumaczenia z z języka lokalnego nalanguageCode
.- Musisz użyć interfejsu IETF kody języków BCP-47, aby określić preferowany język.
-
Jeśli nie podano
languageCode
, interfejs API używa wartości określonej w parametrzeAccept-Language
. Jeśli nie podasz żadnej z tych wartości, domyślną wartością będzieen
Jeśli podasz nieprawidłowy kod języka, interfejs API zwróci błądINVALID_ARGUMENT
błąd. - Preferowany język ma niewielki wpływ na zestaw wyników, które zwracany przez interfejs API i kolejność ich zwrócenia. Dotyczy to również możliwości poprawiania błędów pisowni przez interfejs API.
-
Interfejs API stara się dostarczyć adres, który będzie czytelny zarówno dla użytkownika, jak i
lokalnej populacji, odzwierciedlając jednocześnie dane wejściowe użytkownika. Prognozy miejsc są
formatować się różnie 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 wyrównaniem nazw z preferowanym językiem wskazanym przez parametrlanguageCode
, gdy pod względem ich dostępności, jednak w innych przypadkach używa się nazw najlepiej pasujących do danych wejściowych użytkownika. -
Adresy muszą być sformatowane w lokalnym języku, a alfabet zrozumiały dla użytkownika.
tylko po wybraniu pasujących haseł pasujących do haseł w
input
. -
Pozostałe adresy są zwracane w preferowanym języku, a pasujące hasła mają
został wybrany tak, aby pasował do haseł w parametrze
input
. Jeśli nazwa nie jest dostępny w preferowanym języku, interfejs API używa najbliższego dopasowania.
-
Pasujące hasła w parametrze
Promowanie lokalizacji lub ograniczenie związane z lokalizacją
Możesz wybrać
locationBias
lublocationRestriction
, ale nie jednocześnie, aby zdefiniować obszar wyszukiwania. TraktujlocationRestriction
jako określenie region, w którym muszą się znajdować wyniki, orazlocationBias
jako określenie regionu, w którym wyniki muszą znajdować się w pobliżu, ale mogą się znajdować poza regionem. w pobliżu.locationBias
Określa obszar wyszukiwania. Ta lokalizacja działa dyskryminująco, co oznacza, że wyniki dotyczące określonej lokalizacji, w tym wyniki poza określonym obszarem.
locationRestriction
Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są .
Określ region
locationBias
lublocationRestriction
jako prostokątnego widocznego obszaru lub okręgu.Okrąg jest wyznaczany przez punkt środkowy i promień w metrach. Promień musi się mieścić w zakresie między 0,0 i 50000,0 włącznie. Wartością domyślną jest 0,0. W przypadku usługi
locationRestriction
, musisz ustawić promień na wartość większą niż 0,0. W przeciwnym razie żądanie zwraca Brak 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 szerokości geograficznej, reprezentowany przez dwa elementy. na przekątnej
low
i najwyższych punktach. Widoczny obszar jest uważany za obszar zamknięty, co oznacza, że obejmuje jego granicę. Granice szerokości geograficznej musi mieścić się w przedziale od -90 do 90 stopni włącznie i musi mieścić się w granicach długości geograficznej musi mieścić się w zakresie 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.
Musisz wypełnić zarówno pola
low
, jak ihigh
, a także reprezentowane pole. nie może być pusta. 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 ma zostać obliczona bezpośrednia odległość do miejsce docelowe (zwrócone jako
distanceMeters
). Jeśli ta wartość to zostanie pominięty, odległość wprost nie zostanie zwrócona. Wartość musi być określona jako współrzędne geograficzne:"origin": { "latitude": 40.477398, "longitude": -74.259087 }
-
regionCode
Kod regionu używany do formatowania odpowiedzi podany jako ccTLD („domena najwyższego poziomu”) dwuznakową. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1. z kilkoma istotnymi wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (co.uk), natomiast kod ISO 3166-1 to „gb”. (technicznie dla funkcji podmiotu „Wielkiej Brytanii i Irlandii Północnej”).
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 generowane przez użytkownika ciągi znaków, które śledzą autouzupełnianie (Nowe) jako „sesje”. Autouzupełnianie (nowość) korzysta z tokenów sesji do Pogrupować fazy zapytania i wyboru wyszukiwania autouzupełniania przez użytkownika w oddzielną sesję w celach rozliczeniowych. Więcej informacji: Tokeny 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 korzysta z metody
Adres IP urządzenia, aby zniekształcać wyniki. Opcjonalnie możesz użyć parametru
locationRestriction
lub locationBias
(ale nie obie te opcje), aby określić obszar wyszukiwania.
locationRestriction
określa obszar do przeszukania. Wyniki poza określonym obszarem
nie są zwracane. W poniższym przykładzie używasz locationRestriction
do ograniczenia
do okręgu o promieniu 5000 metrów ze środkiem 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 przypadku funkcji locationBias
lokalizacja działa jako stronniczość, czyli wyniki w okolicy
można zwrócić określoną lokalizację, łącznie z wynikami spoza określonego obszaru. W ciągu następnych
na przykład zmień żą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
Parametr includedPrimaryTypes
umożliwia określenie maksymalnie 5 typów wartości z zakresu
Tabela A
Tabela B,
albo tylko (regions)
lub tylko (cities)
. Miejsce musi pasować do jednego z podanych
podstawowych wartości typów, które mają być uwzględnione w odpowiedzi.
W poniższym przykładzie określasz ciąg input
„Piłka nożna” i użyj parametru includedPrimaryTypes
, aby ograniczyć wyniki do
instytucje 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 wybranego typu, takich jak "athletic_field"
.
Żądanie prognoz zapytań
Prognozy zapytań nie są domyślnie zwracane. Użyj funkcji includeQueryPredictions
żądania, aby dodać do odpowiedzi prognozy zapytań. 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ń
jak pokazano powyżej w sekcji Informacje o odpowiedzi. Każda prognoza zapytania
zawiera pole text
zawierające zalecany ciąg wyszukiwania tekstowego. Możesz
Wyszukiwanie tekstowe (nowość)
żądania, 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 użyjesz właściwości origin
, interfejs API uwzględni pole distanceMeters
w polu
odpowiedź zawierającą 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 wysyłanie przykładowych żądań, aby zapoznać się z interfejsem API i jego opcjami.
- Kliknij ikonę interfejsu API
. w prawej części strony.
- Opcjonalnie rozwiń opcję Pokaż parametry standardowe i ustaw
parametr
fields
do maski pola. - Opcjonalnie edytuj Treść żądania.
- Kliknij przycisk Wykonaj. W wyskakującym okienku wybierz konto, z którego chcesz przesłać prośbę.
W panelu Eksplorator API kliknij ikonę rozwijania.
, aby rozwinąć okno Eksploratora interfejsów API.