Autouzupełnianie (nowość)

Autouzupełnianie (nowa wersja) 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 przez użytkownika tekstu, 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 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.
• Pobieranie prognoz dotyczących miejsc w sposób automatyczny: wywołuj interfejs API bezpośrednio, aby pobierać prognozy i wyświetlać je w niestandardowym interfejsie użytkownika.

Dodawanie widżetu Autouzupełnianie 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 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 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:

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

2. Zdefiniuj autocompleteIntent z odpowiednimi parametrami i tokenem sesji.

3. Określ ActivityResultLauncher dla StartActivityForResult. Ten program uruchamiający obsłuży wynik zwrócony z aktywności autouzupełniania.

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

5. Uruchom intencję za pomocą placeAutocompleteActivityResultLauncher.

Poniższe przykłady pokazują, jak dodać widżet autouzupełniania miejsca w językach Kotlin i 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.
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 dowolny z domyślnych atrybutów stylu. Możesz dostosować kolory, typografię, odstępy, obramowania i rogi 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.

Możesz zdefiniować zastąpienia motywu 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>

Style zastępujące możesz wywoływać za pomocą funkcji 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);

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 dotyczące autouzupełniania (nowe)

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 przewidywanego 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 przy użyciu 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. 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ć obiekt Place. Więcej informacji o identyfikatorach miejsc w autouzupełnianiu znajdziesz w sekcji 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 tym miejscem.
• getDistanceMeters() zwraca odległość w metrach w linii prostej między tym miejscem a miejscem 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 pasujące propozycje 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. Typem podstawowym może być np. "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 typów podstawowych, 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 i includedRegionCodes, 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 danych wejściowych

  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 przyjmuje długość zapytania.

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

• Ograniczenie dotyczące lokalizacji lub preferencje dotyczące 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 wskazówka, a nie ograniczenie, więc wyniki spoza określonego obszaru mogą być nadal zwracane.

    Aby ustawić parametr odchylenia 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, 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 wyników.

  • Prostokąt to widoczny obszar określony przez szerokość i długość geograficzną, reprezentowany przez 2 punkty low i high położone po przekątnej. 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, 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 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, 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 istotnymi 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 funkcji fetchPlace(), aby pobrać szczegóły miejsca wybranego przez użytkownika.

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

  Więcej informacji znajdziesz w sekcji Tokeny sesji.

Przykłady autouzupełniania (nowość)

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 preferencji 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 kolejnym 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 ciąg zapytania to „Piłka nożna”, a parametr primarytypes ogranicza wyniki 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ć 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());
        })
    );

Optymalizacja autouzupełniania (nowość)

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

Oto kilka ogólnych wskazówek:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania (nowego) w interfejsie Maps JavaScript API, widżetu autouzupełniania (nowego) w pakiecie SDK Miejsc na Androida lub widżetu autouzupełniania (nowego) w pakiecie SDK Miejsc na iOS.
• Poznaj najważniejsze pola danych autouzupełniania (nowość) od samego początku.
• Pola dotyczące preferowania lokalizacji i ograniczania lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na skuteczność autouzupełniania.
• Używaj obsługi błędów, aby zapewnić prawidłowe działanie aplikacji, gdy interfejs API zwróci błąd.
• Sprawdź, czy aplikacja obsługuje sytuacje, w których użytkownik nie dokonał wyboru, i czy oferuje mu możliwość kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

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

Zaawansowana optymalizacja kosztów

Rozważ programowe wdrożenie Autocomplete (New), aby uzyskać dostęp do SKU: Autocomplete Request pricing i wysyłać zapytania o wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast szczegółów miejsca (nowych). Ceny za żądanie w połączeniu z interfejsem Geocoding API są bardziej opłacalne niż ceny za sesję (oparte na sesjach), jeśli spełnione są oba te warunki:

• Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego miejsca, interfejs Geocoding API dostarczy te informacje za niższą cenę niż wywołanie interfejsu Place Details (New).
• Jeśli użytkownicy wybierają prognozę autouzupełniania w ramach średnio 4 lub mniej żądań prognoz autouzupełniania (nowych), cena za żądanie może być bardziej opłacalna niż cena za sesję.

Czy Twoja aplikacja wymaga innych informacji niż adres i szerokość/długość geograficzna wybranej prognozy?

Sprawdzone metody dotyczące wydajności

Poniższe wytyczne opisują sposoby optymalizacji skuteczności autouzupełniania (nowego):

• Dodaj do implementacji Autocomplete (New) ograniczenia dotyczące kraju, ustawienia lokalizacji i (w przypadku implementacji programowych) preferencje językowe. W przypadku widżetów nie trzeba określać preferencji językowych, ponieważ są one pobierane z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli usłudze Autouzupełnianie (nowa) towarzyszy mapa, możesz określić lokalizację na podstawie widocznego obszaru mapy.
• Jeśli użytkownik nie wybierze żadnej z podpowiedzi Autocomplete (New), zwykle dlatego, że żadna z nich nie jest szukanym adresem, możesz ponownie użyć pierwotnego tekstu wpisanego przez użytkownika, aby uzyskać bardziej trafne wyniki:
  • Jeśli oczekujesz, że użytkownik wpisze tylko informacje o adresie, użyj ponownie pierwotnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania Szczegóły miejsca (nowe). Jeśli wyniki mają być wyświetlane tylko w określonym regionie, użyj ustawień lokalizacji.
  Inne scenariusze, w których warto wrócić do Geocoding API:
  • użytkownicy wpisujący adresy podrzędne, np. adresy konkretnych lokali lub mieszkań w budynku; Na przykład czeski adres „Stroupežnického 3191/17, Praha” generuje częściową podpowiedź w usłudze Autouzupełnianie (nowa wersja).
  • Użytkownicy wpisujący adresy z prefiksami odcinków dróg, np. „23–30 29th St, Queens” w Nowym Jorku lub „47–380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Preferowanie lokalizacji

Aby zawęzić wyniki do określonego obszaru, przekaż parametr location i parametr radius. To polecenie informuje usługę Autocomplete (New), że ma preferować wyświetlanie wyników w określonym obszarze. Wyniki spoza zdefiniowanego obszaru mogą być nadal wyświetlane. Możesz użyć parametru components, 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 zdefiniowanego przez parametr location i radius, dodając parametr locationRestriction. To polecenie informuje interfejs Autocomplete (New), że ma zwracać tylko wyniki z tego regionu.