Autouzupełnianie (nowa wersja) zwraca prognozy miejsc w odpowiedzi na żądanie, które zawiera ciąg tekstowy wyszukiwania i granice geograficzne kontrolujące obszar wyszukiwania. Autouzupełnianie może dopasowywać całe słowa i podciągi wejściowe, rozwiązując nazwy miejsc, adresy i kody pocztowe. Aplikacja może wysyłać zapytania w miarę wpisywania przez użytkownika tekstu, aby na bieżąco wyświetlać prognozy dotyczące miejsc i zapytań.
Na przykład wywołujesz funkcję autouzupełniania, podając jako argument ciąg znaków zawierający częściowe dane wejściowe użytkownika „Sicilian piz”, a obszar wyszukiwania ograniczony do San Francisco w Kalifornii. Odpowiedź zawiera listę prognozowanych miejsc pasujących do ciągu znaków i obszaru wyszukiwania, np. restaurację o nazwie „Sicilian Pizza Kitchen”.
Zwrócone prognozy miejsc są przeznaczone do wyświetlenia użytkownikowi, aby ułatwić mu wybór pożądanego miejsca. Aby uzyskać więcej informacji o dowolnym z zwróconych przewidywanych miejsc, możesz wysłać żądanie Szczegóły miejsca (nowe).
Prośby o autouzupełnianie (nowe)
Aplikacja może uzyskać listę przewidywanych nazw miejsc lub adresów z interfejsu Autocomplete API, wywołując interfejs PlacesClient.findAutocompletePredictions()
, przekazując obiekt FindAutocompletePredictionsRequest
. Przykład poniżej pokazuje pełne wywołanie funkcji PlacesClient.findAutocompletePredictions()
.
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Sicilian piz") .setRegionCode("ES") .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
Odpowiedzi na „Autouzupełnianie” (nowe)
Interfejs API zwraca FindAutocompletePredictionsResponse
w pliku Task
.
Obiekt FindAutocompletePredictionsResponse
zawiera listę maksymalnie 5 obiektów AutocompletePrediction
reprezentujących przewidywane miejsca. Lista może być pusta, jeśli nie ma żadnych znanych miejsc odpowiadających zapytaniu i kryteriom filtra.
W przypadku każdego przewidywanego miejsca możesz wywołać te metody, aby uzyskać szczegóły miejsca:
getFullText(CharacterStyle)
zwraca pełny tekst opisu miejsca. Jest to kombinacja tekstu głównego i dodatkowego. Przykład: „Wieża Eiffla, aleja Anatole France, Paryż, Francja”. Dodatkowo ta metoda umożliwia wyróżnienie sekcji opisu, które pasują do wyszukiwania, za pomocą wybranego stylu (CharacterStyle
). ParametrCharacterStyle
jest opcjonalny. Jeśli nie potrzebujesz podświetlania, ustaw tę wartość na null.getPrimaryText(CharacterStyle)
zwraca główny tekst opisujący miejsce. Zazwyczaj jest to nazwa miejsca. Przykłady: „Wieża Eiffla” i „123 ul. Pitt”.getSecondaryText(CharacterStyle)
zwraca tekst dodatkowy opisu miejsca. Jest to przydatne, na przykład jako drugi wiersz podczas wyświetlania przewidywań autouzupełniania. Przykłady: „Avenue Anatole France, Paryż, Francja” i „Sydney, Nowa Południowa Walia”.getPlaceId()
zwraca identyfikator miejsca przewidywanego miejsca. Identyfikator miejsca to tekstowy identyfikator jednoznacznie identyfikujący miejsce, którego możesz użyć do ponownego pobrania obiektuPlace
. Więcej informacji o identyfikatorach miejsc w autouzupełnianiu znajdziesz w artykule Szczegóły miejsca (nowy). Ogólne informacje o identyfikatorach miejsc znajdziesz w artykule Identyfikator miejsca – omówienie.getTypes()
zwraca listę typów miejsc powiązanych z tym miejscem.getDistanceMeters()
zwraca odległość w metrach na linii prostej między tym miejscem a punktem początkowym określonym w żądaniu.
Wymagane parametry
-
Zapytanie
ciąg tekstowy, w którym ma być przeprowadzone wyszukiwanie; Określ pełne słowa i podciągi znaków, nazwy miejsc, adresy i kody pocztowe. Usługa Autocomplete (New) zwraca dopasowania na podstawie tego ciągu znaków i porządkuje wyniki według ich trafności.
Aby ustawić parametr zapytania, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetQuery()
.
Parametry opcjonalne
-
Typy podstawowe
Lista maksymalnie 5 wartości typu z tablic Table A lub Table B, która służy do filtrowania miejsc zwracanych w odpowiedzi. Aby miejsce zostało uwzględnione w odpowiedzi, musi odpowiadać jednej z podanych wartości typu podstawowego.
Miejsce może mieć tylko jeden podstawowy typ z typów tabeli A lub tabeli B powiązanych z tym miejscem. Na przykład typ podstawowy może być
"mexican_restaurant"
lub"steak_house"
.Prośba zostanie odrzucona z błędem
INVALID_REQUEST
, jeśli:- Podano więcej niż 5 typów.
- Wszelkie nierozpoznane typy są określane.
Aby ustawić parametr primary_types, wywołaj metodę
setTypesFilter()
podczas tworzenia obiektuFindAutocompletePredictionsRequest
. -
Kraje
Uwzględniaj tylko wyniki z listy określonych krajów, która jest określona jako lista maksymalnie 15-znakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli nie zostanie podany, nie zostaną zastosowane żadne ograniczenia odpowiedzi. Aby na przykład ograniczyć regiony do Niemiec i Francji:
Jeśli określisz zarówno parametr
locationRestriction
, jak iincludedRegionCodes
, wyniki będą się znajdować w obszarze przecięcia tych 2 ustawień.Aby ustawić parametr countries, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetCountries()
. -
przesunięcie wejścia,
Odsunięcie znaku Unicode od 0, wskazujące pozycję kursora w zapytaniu. Pozycja kursora może wpływać na prognozy zwracane przez model. Jeśli to pole jest puste, domyślnie zostanie ustawiona długość zapytania.
Aby ustawić parametr offsetu wejścia, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetInputOffset()
. Ustawienie preferencji dotyczących lokalizacji lub ograniczenie dotyczące lokalizacji
Aby określić obszar wyszukiwania, możesz podać preferencje dotyczące lokalizacji lub ograniczenie lokalizacji, ale nie oba te ustawienia. Ograniczenie lokalizacji to określenie regionu, w którym muszą znajdować się wyniki, a uwzględnienie lokalizacji to określenie regionu, w pobliżu którego muszą znajdować się wyniki. Główna różnica polega na tym, że przy uwzględnieniu lokalizacji wyniki mogą być zwracane poza określony region.
Uwzględnianie lokalizacji
Określa obszar wyszukiwania. Ta lokalizacja służy do ukierunkowania wyników, a nie do ich ograniczenia, więc wyniki poza określonym obszarem mogą być nadal zwracane.
Aby ustawić parametr „location_bias”, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetLocationBias()
.Ograniczenie dotyczące lokalizacji
Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane.
Aby ustawić parametr ograniczenia lokalizacji, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetLocationRestriction()
.
Określ region z uwzględnieniem lokalizacji lub region z ograniczeniem lokalizacji jako prostokątny obszar widoczny lub okrąg.
Okrąg jest definiowany przez punkt środkowy i promień w metrach. Promień musi mieścić się w przedziale od 0,0 do 50 000,0. Wartością domyślną jest 0,0. W przypadku ograniczenia dotyczącego lokalizacji promień musi mieć wartość większą niż 0,0. W przeciwnym razie żądanie nie zwraca żadnych wyników.
Prostokąt to widoczny obszar z uwzględnieniem szerokości i długości geograficznej, reprezentowany przez 2 punkty
low
ihigh
, leżące na przekątnej. Widoczny obszar jest uważany za zamknięty obszar, co oznacza, że obejmuje swoją krawędź. Granice szerokości geograficznej muszą mieścić się w przedziale od -90 do 90 stopni, a granice długości geograficznej – w przedziale od -180 do 180 stopni:- 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°). - 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.
Wartości
low
ihigh
muszą być wypełnione, a reprezentowane pole nie może być puste. Pusta wizjer prowadzi do błędu.- Jeśli
-
Punkt początkowy
Punkt początkowy, z którego obliczana jest odległość w linii prostej do miejsca docelowego (dostępny za pomocą parametru
getDistanceMeters()
). Jeśli ta wartość zostanie pominięta, odległość w linii prostej nie zostanie zwrócona. Musi być podany jako współrzędne szerokości i długości geograficznej:Aby ustawić parametr origin, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetOrigin()
. -
Kod regionu
Kod regionu użyty do sformatowania odpowiedzi, w tym adresu, podany jako kod kraju domeny najwyższego poziomu („top-level domain”) o dwóch znakach. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma wyjątkami. Na przykład ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”).
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ących przepisów.Aby ustawić parametr kodu regionu, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetRegionCode()
. -
Token sesji
Tokeny sesji to tworzone przez użytkownika ciągi znaków, które śledzą wywołania funkcji Autouzupełnianie (nowa) jako „sesje”. Autouzupełnianie używa tokenów sesji, aby grupować fazy zapytania i wyboru w wyszukiwaniu autouzupełniania użytkownika w oddzielne sesje na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierze miejsce. Każda sesja może zawierać wiele zapytań, po których następuje wybór jednego miejsca. Po zakończeniu sesji token traci ważność. Aplikacja musi wygenerować nowy token na każdą sesję. Zalecamy używanie tokenów sesji w przypadku wszystkich sesji automatycznego uzupełniania w ramach programowania (gdy umieszczasz fragment lub uruchamiasz automatyczne uzupełnianie za pomocą intencji, interfejs API zrobi to automatycznie).
Autouzupełnianie używa parametru
AutocompleteSessionToken
do identyfikowania każdej sesji. Aplikacja powinna przekazać nowy token sesji na początku każdej nowej sesji, a potem ten sam token wraz z identyfikatorem miejsca w kolejnych wywołaniachfetchPlace()
, aby pobrać szczegóły miejsca wybranego przez użytkownika.Aby ustawić parametr tokenu sesji, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetSessionToken()
.Więcej informacji znajdziesz w artykule Tokeny sesji.
Przykłady autouzupełniania (nowa wersja)
Używanie ograniczeń dotyczących lokalizacji i uwzględniania lokalizacji
Autouzupełnianie (nowa wersja) domyślnie używa ukierunkowania adresu IP do kontrolowania obszaru wyszukiwania. W przypadku użycia ukierunkowania na adres IP interfejs API używa adresu IP urządzenia, aby ukierunkować wyniki. Aby określić obszar wyszukiwania, możesz opcjonalnie użyć ograniczenia lokalizacji lub preferencji lokalizacji (nie obu jednocześnie).
Ograniczenie dotyczące lokalizacji określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W tym przykładzie używamy ograniczenia dotyczącego lokalizacji, aby ograniczyć żądanie do koła o promieniu 5000 metrów, którego środek znajduje się w San Francisco:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
W przypadku użycia lokalizacji jako czynnika preferencji lokalizacja służy jako czynnik preferencji, co oznacza, że wyniki mogą być zwracane w pobliżu określonej lokalizacji, w tym poza nią. W następnym przykładzie zmieniamy poprzednie zapytanie, aby wykorzystać uczenie z uwzględnieniem lokalizacji:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setLocationBias(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
Używanie typów podstawowych
Użyj parametru primary_types, aby ograniczyć wyniki żądania do określonego typu, jak podano w tabeli A i tabeli B. Możesz podać tablicę zawierającą maksymalnie 5 wartości. Jeśli nie zostanie podany, zwrócone zostaną wszystkie typy.
W tym przykładzie łańcuch zapytania to „Soccer”, a parametr primarytypes służy do ograniczania wyników do obiektów typu "sporting_goods_store"
:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store"); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Soccer") .setIncludedPrimaryTypes(primaryTypes) .setLocationBias(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
Jeśli pominiesz parametr primary_types, wyniki mogą obejmować obiekty typu, którego nie chcesz, np. "athletic_field"
.
Użyj punktu początkowego
Jeśli w żądaniu podasz parametr origin podany jako współrzędne szerokości i długości geograficznej, interfejs API uwzględni w odpowiedzi odległość w linii prostej od punktu początkowego do docelowego (dostępny za pomocą parametru getDistanceMeters()
). W tym przykładzie punkt początkowy to centrum San Francisco:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setOrigin(center) .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
Atrybucje
Możesz używać funkcji Autouzupełnianie (nowa) nawet bez mapy. Jeśli chcesz wyświetlić mapę, musi to być mapa Google. Jeśli wyświetlasz prognozy z usługi Autocomplete (Nowa) bez mapy, musisz uwzględnić logo Google wyświetlane w polu wyszukiwania lub w wynikach. Więcej informacji znajdziesz w artykule Wyświetlanie logo i tekstu atrybucji Google.