Autouzupełnianie (nowe) zwraca prognozy miejsc w odpowiedzi na żądanie, które zawiera ciąg tekstowy wyszukiwania i granice geograficzne określające obszar wyszukiwania. Autouzupełnianie może dopasowywać całe słowa i podciągi tekstu wejściowego, rozwiązując nazwy miejsc, adresy i kody plus. Aplikacja może wysyłać zapytania w trakcie wpisywania tekstu przez użytkownika, aby na bieżąco wyświetlać prognozy dotyczące miejsc i zapytań.
Na przykład wywołujesz autouzupełnianie, używając jako danych wejściowych ciągu znaków zawierającego częściowe dane wejściowe użytkownika „Sicilian piz” z obszarem wyszukiwania ograniczonym do San Francisco w Kalifornii. Odpowiedź zawiera listę prognoz miejsc pasujących do ciągu wyszukiwania i obszaru wyszukiwania, np. restauracji o nazwie „Sicilian Pizza Kitchen”. Zwrócone prognozy miejsc są przeznaczone do wyświetlania użytkownikowi, aby ułatwić mu wybór odpowiedniego miejsca. Możesz wysłać żądanie Szczegóły miejsca (nowe), aby uzyskać więcej informacji o dowolnej z zwróconych prognoz dotyczących miejsc.
Funkcję autouzupełniania (nową) możesz zintegrować z aplikacją na 2 główne sposoby:
- Dodaj widżet autouzupełniania miejsc:
zapewnia gotowe do użycia autouzupełnianie wyszukiwania za pomocą klasy
PlaceAutocomplete
, która wyświetla prognozy podczas wpisywania znaków przez użytkownika. - Automatyczne uzyskiwanie prognoz dotyczących miejsc: wywołuj interfejs API bezpośrednio, aby pobierać prognozy i wyświetlać je w niestandardowym interfejsie użytkownika.
Dodawanie widżetu autouzupełniania miejsc
Aby łatwiej zapewnić spójne działanie autouzupełniania miejsc, możesz dodać do aplikacji widżet autouzupełniania miejsc. Widżet ten udostępnia dedykowany interfejs pełnoekranowy, który obsługuje dane wejściowe użytkownika i wyświetla prognozowane miejsca, a jednocześnie zwraca do aplikacji obiekty AutocompletePrediction
. Następnie możesz wysłać żądanie Szczegóły miejsca (nowe), aby uzyskać dodatkowe informacje o dowolnym z prognozowanych miejsc.
Podobnie jak w przypadku programowego uzyskiwania prognoz dotyczących miejsc, widżet autouzupełniania miejsc umożliwia używanie tokenów sesji do grupowania żądań autouzupełniania w sesje na potrzeby rozliczeń. Podczas tworzenia intencji widżetu możesz przekazać token sesji, wywołując funkcję setAutocompleteSessionToken()
. Jeśli nie podasz tokena sesji, widżet utworzy go za Ciebie. Możesz uzyskać do niego dostęp, wywołując funkcję getSessionTokenFromIntent()
. Więcej informacji o używaniu tokenów sesji znajdziesz w artykule Tokeny sesji.
Aby dodać do aplikacji widżet autouzupełniania miejsc:
(Opcjonalnie) Zdefiniuj token sesji. Jeśli nie podasz tokena sesji, widżet utworzy go za Ciebie.
Zdefiniuj
autocompleteIntent
z odpowiednimi parametrami i tokenem sesji.Określ
ActivityResultLauncher
dlaStartActivityForResult
. Ten program uruchamiający obsłuży wynik zwrócony przez działanie autouzupełniania.Obsłuż wynik w wywołaniu zwrotnym
ActivityResultLauncher
. Obejmuje to wyodrębnianieAutocompletePrediction
iAutocompleteSessionToken
(jeśli nie podano własnych), obsługę błędów i opcjonalnie wysyłanie żądaniafetchPlace()
w celu uzyskania dodatkowych informacji o miejscu.Uruchom intencję za pomocą
placeAutocompleteActivityResultLauncher
.
Te przykłady pokazują, jak dodać widżet autouzupełniania miejsca w językach Kotlin i Java:
Kotlin
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key) // Optional, create a session token for Autocomplete request and the followup FetchPlace request. val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance() val autocompleteIntent: Intent = PlaceAutocomplete.createIntent(this) { // ... provide input params for origin, countries, types filter ... setAutocompleteSessionToken(sessionToken) } val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> val intent = result.data if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object val prediction: AutocompletePrediction? = PlaceAutocomplete.getPredictionFromIntent(intent!!) // get session token val sessionToken: AutocompleteSessionToken? = PlaceAutocomplete.getSessionTokenFromIntent(intent!!) // create PlacesClient to make FetchPlace request (optional) val placesClient: PlacesClient = Places.createClient(this) val response = placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME) { sessionToken = sessionToken // optional } } } // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)
Java
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key); // Optional, create a session token for Autocomplete request and the followup FetchPlace request AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance(); Intent autocompleteIntent = new PlaceAutocomplete.IntentBuilder() // ... set input params for origin, countries, types filter ... .setSessionToken(sessionToken) // optional .build(this); ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent( Preconditions.checkNotNull(intent)); // get session token AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent( Preconditions.checkNotNull(intent)); // create PlacesClient to make FetchPlace request (optional) PlacesClient placesClient = Places.createClient(this); FetchPlaceRequest request = FetchPlaceRequest.builder(prediction.getPlaceId(), Arrays.asList(Field.DISPLAY_NAME)) .setSessionToken(sessionToken).build(); Task<FetchPlaceResponse> task = placesClient.fetchPlace(request); } } } ); // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);
Programowe uzyskiwanie prognoz dotyczących miejsc
Aplikacja może pobrać listę przewidywanych nazw miejsc lub adresów z interfejsu Autocomplete API, wywołując PlacesClient.findAutocompletePredictions()
i przekazując obiekt FindAutocompletePredictionsRequest
. Poniższy przykład 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 (nowość)
Interfejs API zwraca wartość FindAutocompletePredictionsResponse
w Task
.
Obiekt FindAutocompletePredictionsResponse
zawiera listę maksymalnie 5 obiektów AutocompletePrediction
reprezentujących przewidywane miejsca. Lista może być pusta, jeśli nie ma znanego miejsca odpowiadającego zapytaniu i kryteriom filtrowania.
W przypadku każdego prognozowanego miejsca możesz wywołać te metody, aby pobrać szczegóły miejsca:
getFullText(CharacterStyle)
zwraca pełny tekst opisu miejsca. Jest to połączenie tekstu podstawowego i dodatkowego. Przykład: „Wieża Eiffla, aleja Anatole'a France'a, Paryż, Francja”. Dodatkowo ta metoda umożliwia wyróżnienie fragmentów opisu pasujących do wyszukiwania za pomocą wybranego stylu, używającCharacterStyle
. ParametrCharacterStyle
jest opcjonalny. Jeśli nie potrzebujesz wyróżniania, ustaw wartość null.getPrimaryText(CharacterStyle)
zwraca główny tekst opisujący miejsce. Zazwyczaj jest to nazwa miejsca. Przykłady: „Wieża Eiffla” i „ul. Pitta 123”.getSecondaryText(CharacterStyle)
zwraca tekst pomocniczy opisu miejsca. Jest to przydatne np. jako drugi wiersz podczas wyświetlania podpowiedzi autouzupełniania. Przykłady: „Avenue Anatole France, Paris, France” i „Sydney, New South Wales”.getPlaceId()
zwraca identyfikator miejsca przewidywanego miejsca. Identyfikator miejsca to tekstowy identyfikator, który jednoznacznie identyfikuje miejsce. Możesz go użyć, aby później ponownie pobrać obiektPlace
. Więcej informacji o identyfikatorach miejsc w autouzupełnianiu znajdziesz w sekcji Szczegóły miejsca (nowe). Ogólne informacje o identyfikatorach miejsc znajdziesz w omówieniu identyfikatorów miejsc.getTypes()
zwraca listę typów miejsc powiązanych z tym miejscem.getDistanceMeters()
zwraca odległość w metrach 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 zostać przeprowadzone wyszukiwanie. Określ pełne słowa i podciągi znaków, nazwy miejsc, adresy i kody plus. Usługa Autocomplete (New) zwraca proponowane 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 tabeli A lub tabeli B używanych do filtrowania miejsc zwracanych w odpowiedzi. Aby miejsce zostało uwzględnione w odpowiedzi, musi pasować do jednej z określonych wartości typu podstawowego.
Miejsce może mieć tylko jeden typ podstawowy z tabeli A lub tabeli B. Na przykład typ podstawowy może być
"mexican_restaurant"
lub"steak_house"
.Żądanie zostanie odrzucone z błędem
INVALID_REQUEST
, jeśli:- Określono więcej niż 5 typów.
- Wszystkie nierozpoznane typy są określone.
Aby ustawić parametr primaryTypes, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetTypesFilter()
. -
Kraje
Uwzględniaj tylko wyniki z listy określonych krajów, podanych jako lista maksymalnie 15 dwuznakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli ten parametr zostanie pominięty, do odpowiedzi nie zostaną zastosowane żadne ograniczenia. Aby na przykład ograniczyć regiony do Niemiec i Francji:
Jeśli określisz zarówno
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ściowe
Przesunięcie znaku Unicode liczone od zera, które wskazuje pozycję kursora w zapytaniu. Pozycja kursora może wpływać na zwracane prognozy. Jeśli to pole jest puste, domyślnie używana jest długość zapytania.
Aby ustawić parametr przesunięcia danych wejściowych, wywołaj metodę
setInputOffset()
podczas tworzenia obiektuFindAutocompletePredictionsRequest
. Błąd lokalizacji lub ograniczenie lokalizacji
Aby określić obszar wyszukiwania, możesz podać preferencje lokalizacyjne lub ograniczenia lokalizacyjne, ale nie oba te ustawienia naraz. Ograniczenie lokalizacji określa region, w którym muszą się znajdować wyniki, a odchylenie lokalizacji określa region, w pobliżu którego muszą się znajdować wyniki. Główna różnica polega na tym, że w przypadku preferencji lokalizacji mogą być zwracane wyniki spoza określonego regionu.
Obciążenie lokalizacją
Określa obszar wyszukiwania. Ta lokalizacja służy jako punkt odniesienia, a nie ograniczenie, więc mogą być zwracane wyniki spoza określonego obszaru.
Aby ustawić parametr odchylenia lokalizacji, 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, w którym ma być stosowane odchylenie lub ograniczenie lokalizacji, jako prostokątny widoczny obszar 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 włącznie. Wartością domyślną jest 0,0. W przypadku ograniczenia lokalizacji musisz ustawić promień na wartość większą niż 0,0. W przeciwnym razie żądanie nie zwraca żadnych wyników.
Prostokąt to widoczny obszar określony przez szerokość i długość geograficzną, reprezentowany przez 2 przeciwległe punkty
low
ihigh
. Widoczny obszar jest uważany za zamknięty region, co oznacza, że obejmuje swoje granice. Zakres szerokości geograficznej musi się mieścić w przedziale od -90 do 90 stopni włącznie, a zakres długości geograficznej musi się mieścić w przedziale od -180 do 180 stopni włącznie:- Jeśli
low
=high
, widoczny obszar składa się z tego jednego punktu. - Jeśli
low.longitude
>high.longitude
, zakres długości geograficznej jest odwrócony (widoczny obszar przekracza 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.
Pola
low
ihigh
muszą być wypełnione, a reprezentowane pole nie może być puste. Pusty widok spowoduje błąd.- Jeśli
-
Punkt początkowy
Punkt początkowy, od którego należy obliczyć odległość w linii prostej do miejsca docelowego (dostępny za pomocą
getDistanceMeters()
). Jeśli ta wartość zostanie pominięta, odległość w linii prostej nie zostanie zwrócona. Musi być określony jako współrzędne szerokości i długości geograficznej:Aby ustawić parametr pochodzenia, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetOrigin()
. -
Kod regionu
Kod regionu używany do formatowania odpowiedzi, w tym formatowania adresu, określony jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma wyjątkami. Na przykład krajowa domena najwyższego poziomu Zjednoczonego Królestwa to „uk” (.co.uk), a 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
. W zależności od obowiązujących przepisów parametr może wpływać na wyniki.Aby ustawić parametr kodu regionu, podczas tworzenia obiektu
FindAutocompletePredictionsRequest
wywołaj metodęsetRegionCode()
. -
Token sesji
Tokeny sesji to ciągi znaków generowane przez użytkownika, które śledzą wywołania autouzupełniania (nowego) – zarówno wywołania wykonywane za pomocą widżetu, jak i wywołania programowe – jako „sesje”. Autouzupełnianie używa tokenów sesji do grupowania faz zapytania i wyboru w wyszukiwaniu autouzupełniania użytkownika w osobną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna 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 generować nowy token dla każdej sesji. W przypadku wszystkich sesji automatycznego uzupełniania w ramach automatyzacji (gdy osadzasz fragment lub uruchamiasz automatyczne uzupełnianie za pomocą intencji, interfejs API automatycznie się tym zajmuje) zalecamy używanie tokenów sesji.
Autouzupełnianie używa
AutocompleteSessionToken
do identyfikowania każdej sesji. Po rozpoczęciu każdej nowej sesji aplikacja powinna przekazywać nowy token sesji, a następnie ten sam token wraz z identyfikatorem miejsca w kolejnym wywołaniu funkcjifetchPlace()
, aby pobrać szczegóły miejsca wybranego przez użytkownika.Aby ustawić parametr tokena 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 ograniczenia lokalizacji i preferencji lokalizacji
Autouzupełnianie (nowe) domyślnie korzysta z określania obszaru wyszukiwania na podstawie adresu IP. W przypadku określania preferencji na podstawie adresu IP interfejs API używa adresu IP urządzenia do określania preferencji wyników. Możesz opcjonalnie użyć ograniczenia lokalizacji lub odchylenia lokalizacji, ale nie obu tych opcji jednocześnie, aby określić obszar wyszukiwania.
Ograniczenie lokalizacji określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W tym przykładzie użyto ograniczenia lokalizacji, aby ograniczyć żądanie do okrągłego obszaru 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 odchylenia związanego z lokalizacją lokalizacja służy jako odchylenie, co oznacza, że mogą być zwracane wyniki z okolic określonej lokalizacji, w tym wyniki spoza określonego obszaru. W następnym przykładzie zmieniamy poprzednie żądanie, aby używać odchylenia 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 wymienionego w tabeli A i tabeli B. Możesz określić tablicę zawierającą maksymalnie 5 wartości. Jeśli nie zostanie podany, zwracane są wszystkie typy.
W tym przykładzie określono ciąg zapytania „Soccer” i użyto parametru primarytypes, aby ograniczyć wyniki 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 uwzględnisz parametr origin określony jako współrzędne geograficzne, interfejs API uwzględni w odpowiedzi odległość w linii prostej od punktu początkowego do miejsca docelowego (dostępną za pomocą getDistanceMeters()
). W tym przykładzie punkt początkowy jest ustawiony na środek 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()); }) );