Autouzupełnianie (nowość)

Autouzupełnianie (nowe) zwraca prognozy miejsc w odpowiedzi na żądanie, które zawiera ciąg wyszukiwania tekstowego i granice geograficzne, które kontrolują obszar wyszukiwania. Autouzupełnianie może dopasowywać pełne 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, które pasują do wyszukiwanego ciągu znaków i obszaru wyszukiwania, np. restaurację 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 informacje o miejscu (nowe), aby uzyskać więcej informacji o zwróconych prognozach 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 tekstu 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 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 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ń. Token sesji możesz przekazać podczas tworzenia intencji widżetu, 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 autocompleteIntent z odpowiednimi parametrami i tokenem sesji.

3. Określ ActivityResultLauncher dla StartActivityForResult. Ten program uruchamiający będzie obsługiwać wynik zwrócony przez aktywność autouzupełniania.

4. Przetwórz wynik w wywołaniu zwrotnym ActivityResultLauncher. Obejmuje to wyodrębnianie AutocompletePrediction i AutocompleteSessionToken (jeśli nie podano 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

Te przykłady pokazują, jak dodać widżet autouzupełniania miejsca za pomocą języków 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 domyślne atrybuty 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 są zastępowane, 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ływać się do stylów zastępujących, wywołując funkcję 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 prognoz dotyczących miejsc

Aplikacja może uzyskać listę przewidywanych nazw miejsc lub adresów z interfejsu API autouzupełniania, wywołując metodę 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 dotyczące autouzupełniania (nowe)

Interfejs API zwraca obiekt FindAutocompletePredictionsResponse w obiekcie 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óły miejsca:

• getFullText(CharacterStyle) zwraca pełny tekst opisu miejsca. Jest to połączenie tekstu podstawowego 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. Pitta 123”.
• getSecondaryText(CharacterStyle) zwraca tekst pomocniczy 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 prognozowanego miejsca. 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 (nowa wersja). 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 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. Możesz podawać pełne słowa i podłańcuchy, nazwy miejsc, adresy i plus codes. Usługa Autouzupełnianie (nowa) zwraca potencjalne dopasowania na podstawie tego ciągu znaków i porządkuje wyniki według ich trafności.

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

Parametry opcjonalne

• Typy główne

  Lista zawierająca maksymalnie 5 wartości typu 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 główny typ z typów wymienionych w 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:

  • Podano 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, podanej 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. Jeśli chcesz na przykład ograniczyć regiony do Niemiec i Francji:

  Jeśli podasz 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 liczone od 0, które wskazuje pozycję kursora w zapytaniu. Pozycja kursora może wpływać na zwracane podpowiedzi. Jeśli pozostawisz to pole puste, domyślnie zostanie użyta 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ć preferencje lokalizacyjne lub ograniczenia lokalizacyjne, ale nie oba te parametry jednocześnie. 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 preferencja, a nie ograniczenie, więc wyniki spoza określonego obszaru mogą być nadal zwracane.

    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, wywołaj metodę setLocationRestriction() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

  Określ region, w którym ma być stosowane odchylenie lub ograniczenie lokalizacji, jako prostokątny widoczny obszar lub okrąg.

  • Okrąg jest zdefiniowany 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 zwraca żadnych wyników.

  • Prostokąt to widoczny obszar określony przez szerokość i długość geograficzną, reprezentowany przez 2 przeciwległe punkty low i high. Okno jest uważane za region zamknięty, co oznacza, że obejmuje swoje granice. Zakres szerokości geograficznej musi mieścić się w przedziale od -90 do 90 stopni włącznie, a zakres długości geograficznej musi mieścić się 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 obszar wyświetlania 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. 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 istotnymi wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii 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. Parametr może wpływać na wyniki zgodnie z obowiązującymi przepisami.

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

• 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 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 zalecamy używanie tokenów sesji (gdy osadzasz fragment lub uruchamiasz automatyczne uzupełnianie za pomocą intencji, interfejs API automatycznie się tym zajmuje).

  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ć 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 sekcji Tokeny sesji.

Przykłady autouzupełniania (nowa wersja)

Korzystanie z ograniczenia lokalizacji i preferencji lokalizacji

Funkcja Autocomplete (nowa) domyślnie korzysta z ustawiania zakresu wyszukiwania na podstawie adresu IP. W przypadku kierowania na podstawie adresu IP interfejs API używa adresu IP urządzenia, aby kierować 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, 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 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 przykładzie poniżej 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 ten parametr zostanie pominięty, zwracane są wszystkie typy.

W tym przykładzie ciąg zapytania to „Soccer”, a parametr primary types 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 primaryTypes, wyniki mogą zawierać obiekty typu, którego możesz nie chcieć, 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 punktu początkowego do miejsca docelowego (dostępną za pomocą getDistanceMeters()). W tym przykładzie punkt początkowy jest ustawiony 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 (nowego).
• Pola ukierunkowania na lokalizację i ograniczenia lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na działanie autouzupełniania.
• Używaj obsługi błędów, aby zapewnić prawidłowe działanie aplikacji, gdy interfejs API zwróci błąd.
• Upewnij się, że aplikacja obsługuje sytuacje, w których użytkownik nie dokonał wyboru, i oferuje mu możliwość kontynuowania.

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

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

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 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 przez użytkownika miejsca, Geocoding API dostarcza te informacje za mniej niż wywołanie informacji o miejscu (New).
• Jeśli użytkownicy wybiorą podpowiedź autouzupełniania w ramach średnio 4 lub mniej żądań podpowiedzi autouzupełniania (nowych), ceny za żądanie mogą być bardziej opłacalne niż ceny 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 Autouzupełniania (nowego) ograniczenia związane z krajem, ustawienia lokalizacji i (w przypadku implementacji automatycznych) ustawienia języka. 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 autouzupełnianiu (nowemu) towarzyszy mapa, możesz dostosować 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 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 oryginalnych 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 informacji o miejscu (nowe). Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj ustawiania lokalizacji.
  Inne scenariusze, w których najlepiej jest użyć Geocoding API, to:
  • Użytkownicy wpisują adresy lokali, np. adresy konkretnych jednostek lub mieszkań w budynku. Na przykład czeski adres „Stroupežnického 3191/17, Praha” daje częściową podpowiedź w autouzupełnianiu (nowym).
  • Użytkownicy wpisujący 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

Aby zawęzić wyniki do określonego obszaru, przekaż parametr location i parametr radius. Ta instrukcja nakazuje usłudze Autocomplete (New) preferować wyświetlanie wyników w określonym obszarze. Wyniki spoza zdefiniowanego obszaru mogą być nadal wyświetlane. Za pomocą parametru includedRegionCodes możesz filtrować wyniki, aby 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. Ta instrukcja nakazuje interfejsowi Autocomplete (New) zwracanie tylko wyników z tego regionu.