Autouzupełnianie (nowość)

Autouzupełnianie (nowe) zwraca podpowiedzi miejsc w odpowiedzi na żądanie, które zawiera ciąg wyszukiwania tekstowego i granice geograficzne, które określają obszar wyszukiwania. Autouzupełnianie może dopasowywać pełne słowa i podłańcuchy danych wejściowych, rozpoznając nazwy miejsc, adresy i plus codes. Aplikacja może wysyłać zapytania podczas wpisywania tekstu przez użytkownika, aby na bieżąco wyświetlać podpowiedzi dotyczące miejsc i zapytań.

Możesz na przykład wywołać autouzupełnianie, używając jako danych wejściowych ciągu znaków, który zawiera częściowe dane wejściowe użytkownika, „Sicilian piz”, z obszarem wyszukiwania ograniczonym do San Francisco w Kalifornii. Odpowiedź zawiera listę podpowiedzi miejsc, które pasują do wyszukiwanego ciągu znaków i obszaru wyszukiwania, np. restaurację o nazwie „Sicilian Pizza Kitchen”. Zwracane podpowiedzi miejsc są przeznaczone do wyświetlania użytkownikowi, aby pomóc mu w wyborze odpowiedniego miejsca. Możesz wysłać żądanie informacji o miejscu (nowe), aby uzyskać więcej informacji o zwróconych podpowiedziach 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 podpowiedzi podczas wpisywania tekstu przez użytkownika.
• Uzyskiwanie podpowiedzi miejsc automatycznie: wywołaj interfejs API bezpośrednio, aby pobrać podpowiedzi i wyświetlić 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 udostępnia dedykowany interfejs pełnoekranowy, który obsługuje dane wejściowe użytkownika i wyświetla mu prognozy miejsc, zwracając do aplikacji obiekty AutocompletePrediction. Następnie możesz wysłać żądanie informacji o miejscu (nowe), aby uzyskać dodatkowe informacje o prognozach miejsc.

Podobnie jak w przypadku pobierania prognoz miejsc automatycznie, 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 dla 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 getSessionTokenFromIntent(). Więcej informacji o korzystaniu z tokenów sesji znajdziesz w artykule Informacje o tokenach sesji.

Aby dodać do aplikacji widżet autouzupełniania miejsc:

1. (Opcjonalnie) Zdefiniuj token sesji. Jeśli nie podasz tokena sesji, widżet utworzy go za Ciebie.

2. Zdefiniuj obiekt autocompleteIntent z odpowiednimi parametrami i tokenem sesji.

3. Zdefiniuj ActivityResultLauncher dla StartActivityForResult. Ten program uruchamiający obsłuży wynik zwrócony przez aktywność autouzupełniania.

4. Przetwórz wynik w wywołaniu zwrotnym ActivityResultLauncher. Obejmuje to wyodrębnianie parametrów AutocompletePrediction i AutocompleteSessionToken (jeśli nie podasz własnych), obsługę błędów i opcjonalnie wysyłanie żądania fetchPlace() w celu uzyskania dodatkowych informacji o miejscu.

5. Uruchom intencję za pomocą placeAutocompleteActivityResultLauncher

Te przykłady pokazują, jak dodać widżet autouzupełniania miejsc za pomocą Kotlina i Javy:

// 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)

// 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);

Dostosowywanie motywu

Podczas tworzenia instancji autouzupełniania możesz określić motyw, który zastąpi domyślne atrybuty stylu. Możesz dostosować kolory, typografię, odstępy, obramowania i narożniki komponentu autouzupełniania miejsc. Wartość domyślna to PlacesMaterialTheme. Wszystkie atrybuty motywu, które nie zostały zastąpione, używają stylów domyślnych.

Zastąpienia motywu możesz zdefiniować w pliku …/res/values/themes.xml. Na przykład:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

Następnie możesz odwołać się do stylów zastępczych, wywołując setAutocompleteUiCustomization:

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

Automatyczne uzyskiwanie podpowiedzi dotyczących miejsc

Aplikacja może uzyskać listę przewidywanych nazw miejsc lub adresów z interfejsu API autouzupełniania, wywołując PlacesClient.findAutocompletePredictions() i przekazując obiekt FindAutocompletePredictionsRequest. Poniższy przykład pokazuje pełne wywołanie metody 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 zwraca obiekt FindAutocompletePredictionsResponse w Task. 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 filtra.

W przypadku każdego przewidywanego miejsca możesz wywołać te metody, aby pobrać szczegółowe informacje o miejscu:

• getFullText(CharacterStyle) zwraca pełny tekst opisu miejsca. Jest to połączenie tekstu głównego i dodatkowego. Przykład: „Wieża Eiffla, Avenue Anatole France, Paryż, Francja”. Dodatkowo ta metoda pozwala wyróżnić sekcje opisu, które pasują do wyszukiwania, za pomocą wybranego stylu, używając CharacterStyle. Parametr CharacterStyle jest opcjonalny. Jeśli nie potrzebujesz wyróżniania, ustaw wartość null.
• getPrimaryText(CharacterStyle) zwraca główny tekst opisujący miejsce. Zwykle jest to nazwa miejsca. Przykłady: „Wieża Eiffla” i „ul. Piotrkowska 123”.
• getSecondaryText(CharacterStyle) zwraca tekst dodatkowy opisu miejsca. Jest to przydatne na przykład jako drugi wiersz podczas wyświetlania podpowiedzi autouzupełniania. Przykłady: „Avenue Anatole France, Paryż, Francja” i „Sydney, Nowa Południowa Walia”.
• getPlaceId() zwraca identyfikator miejsca, które zostało przewidziane. Identyfikator miejsca to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Możesz go użyć, aby później ponownie pobrać obiekt Place. Więcej informacji o identyfikatorach miejsc w autouzupełnianiu znajdziesz w artykule Informacje o miejscu (nowe). Ogólne informacje o identyfikatorach miejsc znajdziesz w omówieniu identyfikatorów miejsc.
• getTypes() zwraca listę typów miejsc powiązanych z danym miejscem.
• getDistanceMeters() zwraca odległość w linii prostej w metrach między tym miejscem a miejscem początkowym określonym w żądaniu.

Wymagane parametry

Zapytanie

Ciąg tekstowy, który ma zostać wyszukany. Podaj pełne słowa i podłańcuchy, nazwy miejsc, adresy i plus codes. Usługa Autouzupełnianie (nowa) 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 zawierająca maksymalnie 5 wartości typów z tabeli A lub tabeli B, które służą do filtrowania miejsc zwracanych w odpowiedzi. Aby miejsce zostało uwzględnione w odpowiedzi, musi odpowiadać jednej z określonych wartości typu podstawowego.

Miejsce może mieć tylko jeden typ podstawowy z typów wymienionych w tabeli A lub tabeli B. Na przykład typem głównym może być "mexican_restaurant" lub "steak_house".

Żądanie zostanie odrzucone z błędem INVALID_REQUEST, jeśli:

• Podano więcej niż 5 typów.
• określono nierozpoznane typy;

Aby ustawić parametr primary types, wywołaj metodę setTypesFilter() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

Kraje

Uwzględniaj tylko wyniki z listy określonych krajów, podanej jako lista maksymalnie 15 dwuznakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli go pominiesz, 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 i includedRegionCodes, wyniki będą znajdować się w obszarze przecięcia tych 2 ustawień.

Aby ustawić parametr countries, wywołaj metodę setCountries() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

Przesunięcie wejściowe

Przesunięcie znaku Unicode w numeracji od zera, które wskazuje pozycję kursora w zapytaniu. Pozycja kursora może wpływać na zwracane podpowiedzi. Jeśli jest puste, domyślnie używana jest długość zapytania.

Aby ustawić parametr przesunięcia danych wejściowych, wywołaj metodę setInputOffset() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

Ustawienie Location bias lub Location restriction

Aby określić obszar wyszukiwania, możesz podać preferencję lokalizacji lub ograniczenie lokalizacji, ale nie obie te wartości. Ograniczenie lokalizacji określa region, w którym muszą znajdować się wyniki, a preferencja lokalizacji – region, w pobliżu którego muszą znajdować się wyniki. Główna różnica polega na tym, że w przypadku lokalizacji preferowanej mogą być zwracane wyniki spoza określonego regionu.

• Błąd związany z lokalizacją

  Określa obszar wyszukiwania. Ta lokalizacja służy jako preferencja, a nie ograniczenie, więc wyniki spoza określonego obszaru mogą być nadal zwracane.

  Aby ustawić parametr faworyzowania lokalizacji, wywołaj metodę setLocationBias() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

• Ograniczenie dotyczące lokalizacji

  Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane.

  Aby ustawić parametr ograniczenia lokalizacji, wywołaj metodę setLocationRestriction() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

Określ region, na który ma być kierowana lokalizacja, lub region, w którym ma być ona ograniczona, 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ść domyślna to 0,0. W przypadku ograniczenia lokalizacji musisz ustawić promień na wartość większą niż 0,0. W przeciwnym razie żądanie nie zwróci żadnych wyników.

• Prostokąt to widoczny obszar szerokości i długości geograficznej, reprezentowany przez 2 punkty low i high po przekątnej. Widoczny obszar jest uważany za region zamknięty, co oznacza, że obejmuje on swoje granice. Szerokość geograficzna musi mieścić się w zakresie od -90 do 90 stopni, a długość geograficzna – 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 przekracza linię długości geograficznej 180 stopni).
  • Jeśli low.longitude = –180 stopni, a high.longitude = 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne.
  • Jeśli low.longitude = 180 stopni, a high.longitude = –180 stopni, zakres długości geograficznej jest pusty.

  Pola low i high muszą być wypełnione, a reprezentowane pole nie może być puste. Pusty widoczny obszar powoduje błąd.

Punkt początkowy

Punkt początkowy, od którego ma być obliczana 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. Muszą być określone jako współrzędne szerokości i długości geograficznej:

Aby ustawić parametr origin, wywołaj metodę setOrigin() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

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 domena 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 na podstawie obowiązujących przepisów.

Aby ustawić parametr kodu regionu, wywołaj metodę setRegionCode() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

Token sesji

Tokeny sesji to generowane przez użytkownika ciągi znaków, które śledzą wywołania autouzupełniania (nowego) – zarówno wywołania wykonywane przez widżet, jak i wywołania automatyczne – jako „sesje”. Autouzupełnianie używa tokenów sesji do grupowania faz zapytania i wyboru wyszukiwania z autouzupełnianiem przez użytkownika w osobną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy, gdy wybiera 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 dla każdej sesji. Zalecamy używanie tokenów sesji we wszystkich sesjach autouzupełniania zautomatyzowanego (gdy umieszczasz fragment lub uruchamiasz autouzupełnianie za pomocą intencji, interfejs API zajmuje się tym automatycznie).

Autouzupełnianie używa AutocompleteSessionToken do identyfikowania każdej sesji. Aplikacja powinna przekazywać nowy token sesji na początku każdej nowej sesji, a następnie przekazywać ten sam token wraz z identyfikatorem miejsca w kolejnym wywołaniu metody fetchPlace(), aby pobrać informacje o miejscu wybranego przez użytkownika.

Aby ustawić parametr tokena sesji, wywołaj metodę setSessionToken() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

Więcej informacji znajdziesz w artykule o tokenach sesji.

Przykłady autouzupełniania (nowa wersja)

Używanie ograniczenia lokalizacji i preferencji lokalizacji

Autouzupełnianie (nowe) domyślnie używa kierowania na adres IP, aby kontrolować obszar wyszukiwania. W przypadku ukierunkowania na adres IP interfejs API używa adresu IP urządzenia, aby ukierunkować wyniki. Możesz opcjonalnie użyć ograniczenia lokalizacji lub preferencji lokalizacji, ale nie obu tych opcji, 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 wokół 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 preferencji lokalizacji lokalizacja służy jako preferencja, co oznacza, że mogą być zwracane wyniki wokół określonej lokalizacji, w tym wyniki spoza określonego obszaru. W następnym przykładzie zmieniamy poprzednie żądanie, aby użyć lokalizacji preferowanej:

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 zostanie pominięty, zwracane są wszystkie typy.

W tym przykładzie ciąg zapytania to „Soccer”, a parametr primary types służy do ograniczenia wyników do placówek 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ć placówki typu, którego nie chcesz, np. "athletic_field".

Użyj punktu początkowego

Gdy w żądaniu uwzględnisz parametr origin określony jako współrzędne szerokości i długości geograficznej, interfejs API uwzględni w odpowiedzi odległość w linii prostej od miejsca rozpoczęcia do miejsca docelowego (dostępną za pomocą getDistanceMeters()). W tym przykładzie miejsce rozpoczęcia jest ustawione na 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());
        })
    );

Optymalizacja autouzupełniania (nowa wersja)

W tej sekcji opisujemy sprawdzone metody, które pomogą Ci w pełni wykorzystać możliwości usługi Autouzupełnianie (nowa).

Oto ogólne wskazówki:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania (nowego) z Maps JavaScript API, widżetu autouzupełniania (nowego) z pakietu SDK Miejsc na Androida lub widżetu autouzupełniania (nowego) z pakietu SDK Miejsc na iOS.
• Od samego początku poznaj najważniejsze pola danych autouzupełniania (nowej wersji).
• Pola ukierunkowania na lokalizację i ograniczenia lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na działanie autouzupełniania.
• Użyj obsługi błędów, aby upewnić się, że aplikacja będzie działać prawidłowo, jeśli interfejs API zwróci błąd.
• Upewnij się, że aplikacja obsługuje sytuację, gdy nie ma wyboru, i oferuje użytkownikom sposób na kontynuowanie.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszty korzystania z usługi Autouzupełnianie (nowa), użyj masek pól w widżetach informacje o miejscu (nowe) i Autouzupełnianie (nowe), aby zwracać tylko potrzebne pola danych Autouzupełniania (nowego).

Zaawansowana optymalizacja kosztów

Rozważ automatyczne wdrożenie autouzupełniania (nowego), aby uzyskać dostęp do SKU: ceny żądań autouzupełniania i poprosić o wyniki Geocoding API dotyczące wybranego miejsca zamiast informacji o miejscu (nowych). Ceny za żądanie w połączeniu z Geocoding API są bardziej opłacalne niż ceny za sesję, jeśli spełnione są oba te warunki:

• Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu miejsca wybranego przez użytkownika, Geocoding API dostarcza te informacje za mniej niż wywołanie informacji o miejscu (New).
• Jeśli użytkownicy wybierają podpowiedź autouzupełniania średnio w ciągu maksymalnie 4 żądań podpowiedzi autouzupełniania (nowych), ceny za żądanie mogą być bardziej opłacalne niż ceny za sesję.

W zależności od wydajności Autouzupełniania (nowego) interfejs Geocoding API może być dla Twojej aplikacji bardziej opłacalny niż informacje o miejscu (nowe). Skuteczność autouzupełniania (nowego) w każdej aplikacji zależy od tego, co wpisują użytkownicy, gdzie aplikacja jest używana i czy wdrożono sprawdzone metody optymalizacji skuteczności.

Aby znaleźć średnią liczbę żądań dla tabeli, przeanalizuj, ile znaków użytkownik wpisuje średnio przed wybraniem podpowiedzi autouzupełniania (nowej) w aplikacji.

Autouzupełnianie (nowe) oparte na sesji z informacjami o miejscu (nowe)

Używaj autouzupełniania opartego na sesji (nowego) z informacjami o miejscu (nowymi).
Ponieważ Twoja aplikacja wymaga informacji o miejscu (nowych), takich jak nazwa miejsca, status firmy lub godziny otwarcia, Twoja implementacja autouzupełniania (nowego) powinna używać tokena sesji (programowo lub wbudowanego w widżety JavaScript, Android lub iOS) na sesję oraz odpowiednich kodów SKU Miejsc, w zależności od tego, o które pola danych miejsca prosisz¹.

Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Android lub iOS. Obejmuje to zarówno żądania autouzupełniania (nowe), jak i żądania dotyczące informacji o miejscu (nowe) w przypadku wybranej podpowiedzi. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko tych pól danych autouzupełniania (nowego), których potrzebujesz.

Implementacja automatyczna
Używaj tokena sesji w żądaniach autouzupełniania (nowych). W żądaniu informacji o miejscu (nowych) dotyczących wybranej podpowiedzi uwzględnij te parametry:

1. Identyfikator miejsca z odpowiedzi Autouzupełniania (nowego).
2. Token sesji użyty w żądaniu Autouzupełniania (nowego).
3. Parametr fields określający potrzebne pola danych autouzupełniania (nowego).

Autouzupełnianie (nowe) na żądanie z Geocoding API

Zaimplementuj Autouzupełnianie (nowe) automatycznie bez tokenów sesji i wywołaj interfejs Geocoding API w przypadku wybranej podpowiedzi miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej. Wykonanie 4 żądań autouzupełniania i wywołanie Geocoding API w przypadku wybranej podpowiedzi miejsca kosztuje mniej niż autouzupełnianie (nowe) na sesję.¹

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby ułatwić użytkownikom uzyskiwanie podpowiedzi, których szukają, przy użyciu jeszcze mniejszej liczby znaków.

Autouzupełnianie (nowe) oparte na sesjach w przypadku aplikacji, które korzystają tylko z adresów

Używaj autouzupełniania opartego na sesji (nowego) z informacjami o miejscu (nowymi).
Średnia liczba żądań, których oczekujesz, zanim użytkownik wybierze podpowiedź autouzupełniania (nowego), przekracza koszt rozliczania za sesję, dlatego Twoja implementacja autouzupełniania (nowego) powinna używać tokena sesji zarówno w przypadku żądań autouzupełniania (nowego), jak i powiązanych żądań informacji o miejscu (nowych) za sesję. ¹

Implementacja widżetu
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Android i iOS. Obejmuje to zarówno żądania autouzupełniania (nowe), jak i żądania dotyczące informacji o miejscu (nowe) w przypadku wybranej podpowiedzi. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko tych pól, których potrzebujesz.

Implementacja automatyczna
Używaj tokena sesji w żądaniach autouzupełniania (nowych). Gdy prosisz o informacje o miejscu (nowe) dotyczące wybranej podpowiedzi, uwzględnij te parametry:

1. Identyfikator miejsca z odpowiedzi Autouzupełniania (nowego).
2. Token sesji użyty w żądaniu Autouzupełniania (nowego).
3. Parametr fields określający pola, takie jak adres i geometria.

Rozważ opóźnienie żądań autouzupełniania (nowa wersja)
Możesz zastosować strategie takie jak opóźnienie żądania autouzupełniania (nowa wersja), dopóki użytkownik nie wpisze pierwszych 3 lub 4 znaków, dzięki czemu aplikacja będzie wysyłać mniej żądań. Jeśli na przykład wysyłasz żądania Autouzupełniania (nowego) dla każdego znaku po wpisaniu przez użytkownika trzeciego znaku, oznacza to, że jeśli użytkownik wpisze 7 znaków, a następnie wybierze podpowiedź, dla której wysyłasz jedno żądanie do interfejsu Geocoding API, łączny koszt będzie obejmował 4 żądania Autouzupełniania (nowego) i żądanie do interfejsu Geocoding API¹.

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań automatycznych spadnie poniżej 4, możesz postępować zgodnie ze wskazówkami dotyczącymi implementacji wydajnego autouzupełniania (nowego) z interfejsem Geocoding API. Pamiętaj, że opóźnianie żądań może być postrzegane przez użytkownika jako opóźnienie, ponieważ może on oczekiwać podpowiedzi po każdym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby pomóc użytkownikom uzyskać podpowiedź, której szukają, przy użyciu mniejszej liczby znaków.

Sprawdzone metody dotyczące skuteczności

Te wskazówki opisują sposoby optymalizacji wydajności autouzupełniania (nowego):

• Dodaj do implementacji Autouzupełniania (nowego) ograniczenia związane z krajem, ustawienia lokalizacji i (w przypadku implementacji automatycznych) ustawienia języka. Ustawienia języka nie są potrzebne w przypadku widżetów, ponieważ pobierają one ustawienia języka z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli autouzupełnianiu (nowemu) towarzyszy mapa, możesz zmienić lokalizację według widocznego obszaru mapy.
• W sytuacjach, gdy użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania (nowego), zwykle dlatego, że żadna z nich nie jest adresem, którego szuka, możesz ponownie użyć oryginalnych danych wejściowych użytkownika, aby spróbować uzyskać trafniejsze wyniki:
  • Jeśli oczekujesz, że użytkownik wpisze tylko informacje o adresie, użyj ponownie oryginalnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli spodziewasz się, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania informacji o miejscu (nowego). Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj ustawienia lokalizacji.
  Inne scenariusze, w których najlepiej jest użyć Geocoding API:
  • Użytkownicy wpisują adresy podlokali, np. adresy konkretnych lokali lub mieszkań w budynku. Na przykład czeski adres „Stroupežnického 3191/17, Praha” zwraca częściową podpowiedź w Autouzupełnianiu (nowym).
  • Użytkownicy wpisują adresy z prefiksami segmentów dróg, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Uwzględnianie lokalizacji

Możesz faworyzować wyniki z określonego obszaru, przekazując parametry location i radius. Dzięki temu autouzupełnianie (nowe) będzie preferować wyświetlanie wyników w określonym obszarze. Wyniki spoza zdefiniowanego obszaru mogą być nadal wyświetlane. Możesz użyć parametru includedRegionCodes, aby filtrować wyniki i wyświetlać tylko miejsca w określonym kraju.

Ograniczanie lokalizacji

Ogranicz wyniki do określonego obszaru, przekazując parametr locationRestriction.

Możesz też ograniczyć wyniki do regionu określonego przez parametry location i radius, dodając parametr locationRestriction. Dzięki temu autouzupełnianie (nowe) zwraca wyniki tylko z tego regionu.