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ć pełne 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 przewidywać miejsca i zapytania.
Na przykład wywołujesz funkcję Autouzupełnianie, podając jako dane wejściowe 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ę „Sicilian Pizza Kitchen”.
Zwrócone prognozy miejsc są przeznaczone do wyświetlania użytkownikowi, aby ułatwić mu wybór odpowiedniego miejsca. Aby uzyskać więcej informacji o dowolnym z zwróconych przewidywanych miejsc, możesz wysłać żądanie Szczegóły miejsca (nowa wersja).
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 autouzupełniania (nowe),
Interfejs API zwracaFindAutocompletePredictionsResponse
w Task
.
Element FindAutocompletePredictionsResponse
zawiera listę maksymalnie 5 obiektów AutocompletePrediction
reprezentujących przewidywane miejsca. Lista może być pusta, jeśli nie ma żadnych znanych miejsc pasujących do zapytania i kryteriów filtra.
Aby pobrać szczegóły przewidywanego miejsca, możesz wywołać te metody:
getFullText(CharacterStyle)
zwraca pełny tekst opisu miejsca. Jest to kombinacja tekstu głównego i dodatkowego. Przykład: „Wieża Eiffla, Avenue Anatole France, Paryż, Francja”. Ponadto 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świetlenia, ustaw tę wartość na null.getPrimaryText(CharacterStyle)
zwraca główny tekst opisujący miejsce. Zwykle jest to nazwa miejsca. Przykłady: „Wieża Eiffla” lub „123 ul. Pitt”.getSecondaryText(CharacterStyle)
zwraca tekst dodatkowy w opisie miejsca. Jest to przydatne, na przykład w przypadku wyświetlania przewidywanej odpowiedzi na drugim wierszu. Przykłady: „Avenue Anatole France, Paris, France” i „Sydney, New South Wales”.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 Informacje o miejscu (nowy). Ogólne informacje o identyfikatorach miejsc znajdziesz w artykule Omówienie identyfikatorów miejsc.getTypes()
zwraca listę typów miejsc powiązanych z tym miejscem.getDistanceMeters()
zwraca w metrach odległość w 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 plus. Usługa Autouzupełnianie (nowa) zwraca dopasowania na podstawie tego ciągu znaków i porządkuje wyniki według ich prawdopodobnego dopasowania.
Aby ustawić parametr zapytania, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetQuery()
.
Parametry opcjonalne
-
Podstawowe typy
Lista maksymalnie 5 wartości typu z tablic tabeli A lub tabeli B, która służy do filtrowania miejsc zwracanych w odpowiedzi. Aby miejsce zostało uwzględnione w odpowiedzi, musi być zgodne z jednym z podanych podstawowych typów.
Miejsce może mieć tylko jeden podstawowy typ z typów Tabela A lub Tabela B powiązanych z tym miejscem. Na przykład typ podstawowy może być
"mexican_restaurant"
lub"steak_house"
.Prośba jest odrzucana z błędem
INVALID_REQUEST
, jeśli:- Określono więcej niż 5 typów.
- Wszelkie nierozpoznane typy są określane.
Aby ustawić parametr primary_types, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetTypesFilter()
. -
Kraje
uwzględniać tylko wyniki z listy określonych krajów, podanych jako lista maksymalnie 15-znakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli to pole zostanie pominięte, 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ą znajdować się 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 zera wskazujące pozycję kursora w zapytaniu. Pozycja kursora może wpływać na wyniki przewidywania. Jeśli jest puste, przyjmuje domyślnie długość zapytania.
Aby ustawić parametr offsetu wejścia, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetInputOffset()
. Uzależnienie od lokalizacji lub ograniczenie dotyczące lokalizacji
Aby określić obszar wyszukiwania, możesz podać preferencje dotyczące lokalizacji lub ograniczenia dotyczące lokalizacji, ale nie obie te opcje jednocześnie. Ograniczenie dotyczące lokalizacji określa region, w którym muszą znajdować się wyniki, a uwzględnienie lokalizacji – region, 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 jako preferencja, a nie ograniczenie, 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 obszar ograniczeń lub preferencji dotyczących lokalizacji jako prostokątny obszar okna lub okrąg.
Okrąg jest definiowany przez punkt środkowy i promień w metrach. Promień musi mieścić się w zakresie od 0,0 do 50 000,0. Wartość domyślna to 0,0. W przypadku ograniczenia lokalizacji musisz ustawić promień na wartość większą niż 0,0. W przeciwnym razie prośba zwraca brak wyników.
Prostokąt to widok z uwzględnieniem szerokości i długości geograficznej, reprezentowany przez 2 punkty
low
ihigh
, które leżą naprzeciw siebie. Widok jest uważany za zamknięty region, co oznacza, że obejmuje swoją granicę. Granice szerokości geograficznej muszą mieścić się w zakresie od –90° do 90°, a granice długości geograficznej – od –180° do 180°:- Jeśli
low
=high
, obszar widoczny składa się z jednego 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, widok 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 reprezentowana kolumna nie może być pusta. 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. Należy je podać w formacie współrzędnych geograficznych: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 ccTLD („domena najwyższego poziomu”)dwucyfrowa wartość. 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), traktując je jako „sesje”. Autouzupełnianie używa tokenów sesji, aby grupować fazy zapytania i wyboru w wyszukiwaniu autouzupełniania użytkownika w oddzielną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, i 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 we wszystkich automatycznych sesjach autouzupełniania (gdy umieszczasz fragment lub uruchamiasz autouzupełnianie za pomocą inencji, 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 dotyczącego lokalizacji lub preferencji dotyczącej lokalizacji, ale nie obu tych opcji 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 z San Francisco jako środkiem:
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 ustawienia lokalizacji jako preferencji wyszukiwania lokalizacja służy jako preferencja, 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 pominiesz ten parametr, zwrócone zostaną wszystkie typy.
W tym przykładzie łańcuch zapytań to „Soccer”, a parametr primary_types 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 (źródło) podany jako współrzędne geograficzne (szerokość i długość geograficzna), interfejs API uwzględni w odpowiedzi odległość w prostą od źródła do miejsca docelowego (dostępna za pomocą parametru getDistanceMeters()
). W tym przykładzie źródło 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ć autouzupełniania (nowego) nawet bez mapy. Jeśli chcesz pokazać mapę, musi to być mapa Google. Jeśli wyświetlasz przewidywania z usługi Autouzupełnianie (Nowa) bez mapy, musisz uwzględnić logo Google wyświetlane w polu wyszukiwania lub w wynikach wyszukiwania. Więcej informacji znajdziesz w artykule Wyświetlanie logo i tekstu atrybucji Google.