Autouzupełnianie miejsc (starsza wersja)

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

Jeśli Twój adres rozliczeniowy znajduje się w Europejskim Obszarze Gospodarczym, od 8 lipca 2025 r. do korzystania z usług będą miały zastosowanie Warunki korzystania z usługi Google Maps Platform w EOG. Funkcje różnią się w zależności od regionu. Więcej informacji

Autouzupełnianie miejsc (starsza wersja) zwraca prognozy miejsc w odpowiedzi na zapytania użytkownika. Gdy użytkownik wpisuje tekst, usługa autouzupełniania zwraca sugestie dotyczące miejsc, takich jak firmy, adresy, kody plus i ciekawe miejsca.

Funkcję autouzupełniania możesz dodać do aplikacji na te sposoby:

• Dodaj widżet autouzupełniania, aby skrócić czas programowania i zapewnić spójne środowisko użytkownika.
• Pobieraj prognozy miejsc w sposób programowy, aby tworzyć spersonalizowane środowisko użytkownika.

Wycofany: widżet autouzupełniania interfejsu Places API (starszego) został wycofany. Przejdź na Autouzupełnianie (nowe), aby używać widżetu Autouzupełnianie (nowe) lub programowo uzyskiwać prognozowane lokalizacje. Pamiętaj, że aby używać widżetu Autocomplete (New), musisz włączyć interfejs Places API (New) w kluczu interfejsu API w konsoli Google Cloud.

Dodawanie widżetu autouzupełniania

Widżet autouzupełniania to okno wyszukiwania z wbudowaną funkcją autouzupełniania. Gdy użytkownik wpisuje wyszukiwane hasła, widżet wyświetla listę przewidywanych miejsc do wyboru. Gdy użytkownik dokona wyboru, zwracana jest instancja Place, której aplikacja może użyć do uzyskania szczegółowych informacji o wybranym miejscu.

Widżet autouzupełniania możesz dodać do aplikacji na 2 sposoby:

• Opcja 1. Umieść AutocompleteSupportFragment.
• Opcja 2. Użyj intencji, aby uruchomić aktywność autouzupełniania

Opcja 1. Umieść fragment AutocompleteSupportFragment

Aby dodać AutocompleteSupportFragment do aplikacji, wykonaj te czynności:

1. Dodaj fragment do układu XML aktywności.
2. Dodaj detektor do aktywności lub fragmentu.

Dodawanie fragmentu AutocompleteSupportFragment do aktywności

Aby dodać AutocompleteSupportFragment do aktywności, dodaj nowy fragment do układu XML. Na przykład:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />

• Domyślnie fragment nie ma obramowania ani tła. Aby zapewnić spójny wygląd, zagnieźdź fragment w innym elemencie układu, np. w CardView.
• Jeśli używasz fragmentu Autocomplete i musisz zastąpić onActivityResult, musisz wywołać super.onActivityResult. W przeciwnym razie fragment nie będzie działać prawidłowo.

Dodawanie detektora PlaceSelectionListener do aktywności

Detektor PlaceSelectionListener obsługuje zwracanie miejsca w odpowiedzi na wybór użytkownika. Ten kod ilustruje utworzenie odwołania do fragmentu i dodanie detektora do elementu AutocompleteSupportFragment:

Kotlin

    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.DISPLAY_NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            binding.autocompleteResult.text = getString(
                R.string.place_selection,
                place.displayName,
                place.id,
                place.formattedAddress
            )
            Log.i(TAG, "Place: ${place.displayName}, ${place.id}")
        }

        override fun onError(status: Status) {
            binding.autocompleteResult.text = getString(R.string.an_error_occurred, status)
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

Java

    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    assert autocompleteFragment != null;
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            binding.autocompleteResult.setText(
                    getString(
                            R.string.place_selection,
                            place.getDisplayName(),
                            place.getId(),
                            place.getFormattedAddress()
                    )
            );
            Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            binding.autocompleteResult.setText(getString(R.string.an_error_occurred, status));
            Log.e(TAG, "An error occurred: " + status);
        }
    });

      

Opcja 2. Użyj intencji, aby uruchomić aktywność autouzupełniania

Jeśli chcesz, aby Twoja aplikacja korzystała z innego sposobu nawigacji (np. aby wywoływać autouzupełnianie za pomocą ikony, a nie pola wyszukiwania), może uruchamiać autouzupełnianie za pomocą intencji.

Uwaga: te czynności nie są potrzebne, jeśli osadzasz fragment.

Ostrzeżenie: NIE uruchamiaj bezpośrednio AutcompleteActivity. Zamiast tego użyj intencji, aby uruchomić Autocomplete (PlaceAutocomplete w bibliotece zgodności).

Aby uruchomić widżet autouzupełniania za pomocą intencji:

1. Aby utworzyć intencję, użyj funkcji Autocomplete.IntentBuilder, przekazując żądany Autocomplete tryb.
2. Zdefiniuj moduł uruchamiający wynik aktywności registerForActivityResult który może służyć do uruchamiania intencji i obsługi wybranego przez użytkownika miejsca w wyniku.

Tworzenie intencji autouzupełniania

W przykładzie poniżej użyto Autocomplete.IntentBuilder do utworzenia intencji uruchamiającej widżet autouzupełniania jako intencję:

Kotlin

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS)

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .build(this)

    startAutocomplete.launch(intent)

      

Java

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME, Place.Field.FORMATTED_ADDRESS);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);
    startAutocomplete.launch(intent);

      

Podczas korzystania z intencji uruchomienia widżetu autouzupełniania możesz wybrać tryb wyświetlania nakładki lub pełnego ekranu. Na zrzutach ekranu poniżej widać poszczególne tryby wyświetlania:

Rysunek 1. Widżet autouzupełniania w trybie OVERLAY

Rysunek 2. Widżet autouzupełniania w trybie PEŁNEGO EKRANU

Rejestrowanie wywołania zwrotnego dla wyniku intencji

Aby otrzymywać powiadomienia, gdy użytkownik wybierze miejsce, zdefiniuj registerForActivityResult()uruchamiacz, który uruchamia działanie i obsługuje wynik, jak pokazano w tym przykładzie. Jeśli użytkownik wybierze prognozę, zostanie ona przekazana w intencji zawartej w obiekcie wyniku. Intencja została utworzona przez Autocomplete.IntentBuilder, więc metoda Autocomplete.getPlaceFromIntent() może z niej wyodrębnić obiekt Place.

Kotlin

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                binding.autocompleteResult.text = getString(
                    R.string.place_selection,
                    place.displayName,
                    place.id,
                    place.formattedAddress)
                Log.i(
                    TAG, "Place: ${place.displayName}, ${place.id}"
                )
            }
        } else if (result.resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
            binding.autocompleteResult.setText(R.string.user_canceled_autocomplete)
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

Java

private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    binding.autocompleteResult.setText(
                            getString(
                                    R.string.place_selection,
                                    place.getDisplayName(),
                                    place.getId(),
                                    place.getFormattedAddress()
                            )
                    );
                    Log.i(TAG, "Place: " + place.getDisplayName() + ", " + place.getId());
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                binding.autocompleteResult.setText(R.string.user_canceled_autocomplete);
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

Automatyczne uzyskiwanie prognoz dotyczących miejsc

Możesz utworzyć niestandardowy interfejs wyszukiwania jako alternatywę dla interfejsu udostępnianego przez widżet autouzupełniania. Aby to zrobić, aplikacja musi uzyskiwać prognozy miejsc programowo. Aplikacja może pobrać listę przewidywanych nazw miejsc lub adresów z interfejsu Autocomplete API, wywołując metodę PlacesClient.findAutocompletePredictions() i przekazując obiekt FindAutocompletePredictionsRequest z tymi parametrami:

• Wymagany: ciąg query zawierający tekst wpisany przez użytkownika.
• Zalecane: A AutocompleteSessionToken, która grupuje fazy zapytania i wyboru w wyszukiwaniu użytkownika w osobną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy, gdy wybierze miejsce.
• Zalecane: obiekt RectangularBounds, który określa granice szerokości i długości geograficznej, aby ograniczyć wyniki do określonego regionu.
• Opcjonalnie: co najmniej 1 dwuliterowy kod kraju (ISO 3166-1 Alpha-2) wskazujący kraj lub kraje, do których powinny być ograniczone wyniki.

• Opcjonalnie: A TypeFilter, którego możesz użyć, aby ograniczyć wyniki do określonego typu miejsca. Obsługiwane są te typy miejsc:

  • TypeFilter.GEOCODE – zwraca tylko wyniki geokodowania, a nie firmy. Użyj tego żądania, aby rozróżnić wyniki, w których określona lokalizacja może być niejednoznaczna.
  • TypeFilter.ADDRESS – zwraca tylko wyniki autouzupełniania z dokładnym adresem. Użyj tego typu, jeśli wiesz, że użytkownik szuka dokładnego adresu.
  • TypeFilter.ESTABLISHMENT – zwraca tylko miejsca, które są firmami.

  • TypeFilter.REGIONS – zwraca tylko miejsca, które pasują do jednego z tych typów:

  • LOCALITY

  • SUBLOCALITY

  • POSTAL_CODE

  • COUNTRY

  • ADMINISTRATIVE_AREA_LEVEL_1

  • ADMINISTRATIVE_AREA_LEVEL_2

  • TypeFilter.CITIES – zwraca tylko wyniki pasujące do LOCALITY lub ADMINISTRATIVE_AREA_LEVEL_3.

• Opcjonalnie: obiekt LatLng określający lokalizację pochodzenia żądania. Gdy wywołasz usługę setOrigin(), zwróci ona odległość w metrach (distanceMeters) od określonego punktu początkowego dla każdej podpowiedzi autouzupełniania w odpowiedzi.

Więcej informacji o typach miejsc znajdziesz w przewodniku po typach miejsc.

Poniższy przykład pokazuje pełne wywołanie funkcji PlacesClient.findAutocompletePredictions().

Kotlin

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            val builder = StringBuilder()
            for (prediction in response.autocompletePredictions) {
                builder.append(prediction.getPrimaryText(null).toString()).append("\n")
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
            binding.autocompleteResult.text = builder.toString()
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
                binding.autocompleteResult.text = getString(R.string.place_not_found, exception.message)
            }
        }

      

Java

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        StringBuilder builder = new StringBuilder();
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            builder.append(prediction.getPrimaryText(null).toString()).append("\n");
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
        binding.autocompleteResult.setText(builder.toString());
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException apiException) {
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
            binding.autocompleteResult.setText(getString(R.string.place_not_found, apiException.getMessage()));
        }
    });

      

Interfejs API zwraca wartość FindAutocompletePredictionsResponse w  Task. FindAutocompletePredictionsResponse zawiera listę 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, aleja Anatole'a France'a, Paryż, Francja”. Dodatkowo ta metoda umożliwia wyróżnienie fragmentów opisu pasujących do wyszukiwania za pomocą wybranego stylu, używając CharacterStyle. Parametr CharacterStyle jest opcjonalny. Jeśli nie potrzebujesz podświetlenia, 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 prognoz 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 pakiecie SDK Miejsc na Androida znajdziesz w sekcji Szczegóły miejsca. Ogólne informacje o identyfikatorach miejsc znajdziesz w omówieniu identyfikatorów miejsc.
• getPlaceTypes() 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.

Uwaga: więcej informacji o inicjowaniu PlacesClient znajdziesz w artykule Inicjowanie klienta interfejsu Places API.

Możesz użyć elementu CancellationToken, aby spróbować anulować żądanie w dowolnej klasie żądań (np. FetchPlaceRequest). Anulowanie jest wykonywane zgodnie z zasadą możliwie najlepszej obsługi. Po wysłaniu prośby o anulowanie nie zostanie zwrócona żadna odpowiedź. Wydanie tokena anulowania NIE gwarantuje, że konkretne żądanie zostanie anulowane, i możesz nadal ponosić opłaty za żądanie, nawet jeśli nie otrzymasz odpowiedzi.

Tokeny sesji

Tokeny sesji grupują fazy zapytania i wyboru autouzupełniania wyszukiwania 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. Zalecamy używanie tokenów sesji we wszystkich sesjach automatycznego uzupełniania w ramach automatyzacji (gdy osadzasz fragment lub uruchamiasz automatyczne uzupełnianie za pomocą intencji, interfejs API automatycznie się tym zajmuje).

Pakiet SDK Miejsc na Androida 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 funkcji fetchPlace(), aby pobrać informacje o miejscu wybranego przez użytkownika.

Wskazówka: jeśli Twoja aplikacja korzysta z widżetu autouzupełniania, nie musisz wdrażać sesji, ponieważ widżet automatycznie obsługuje sesje w tle.

Więcej informacji o tokenach sesji

Ograniczanie wyników autouzupełniania

Możesz ograniczyć wyniki autouzupełniania do określonego regionu geograficznego lub filtrować wyniki według jednego lub kilku typów miejsc albo maksymalnie 5 krajów. Możesz zastosować te ograniczenia do aktywności autouzupełniania, AutocompleteSupportFragment i interfejsów API autouzupełniania w ramach automatyzacji.

Aby ograniczyć wyniki:

• Aby preferować wyniki w określonym regionie, wywołaj funkcję setLocationBias() (mogą być zwracane niektóre wyniki spoza określonego regionu).
• Aby wyświetlać tylko wyniki w określonym regionie, wywołaj setLocationRestriction() (zostaną zwrócone tylko wyniki w określonym regionie).
• Aby zwracać tylko wyniki, które odpowiadają określonemu typowi miejsca, wywołaj funkcję setTypesFilter() (na przykład określenie TypeFilter.ADDRESS spowoduje zwrócenie tylko wyników z dokładnym adresem).
• Aby zwracać tylko wyniki z maksymalnie 5 określonych krajów, wywołaj funkcję setCountries(). Kraje muszą być przekazywane jako dwuznakowy kod kraju zgodny ze standardem ISO 3166-1 alfa-2.

Przekształcanie wyników w określonym regionie

Aby dostosować wyniki autouzupełniania do określonego regionu geograficznego, wywołaj funkcję setLocationBias(), przekazując parametr RectangularBounds. Poniższy przykład kodu pokazuje wywołanie funkcji setLocationBias() w przypadku fragmentu, aby dostosować sugestie autouzupełniania do regionu Sydney w Australii.

Kotlin

        autocompleteFragment.setLocationBias(bounds)

      

Java

        autocompleteFragment.setLocationBias(
                RectangularBounds.newInstance(
                        new LatLng(-33.880490, 151.184363),
                        new LatLng(-33.858754, 151.229596)
                )
        );

      

Ograniczanie wyników do określonego regionu

Aby ograniczyć wyniki autouzupełniania do określonego regionu geograficznego, wywołaj funkcję setLocationRestriction(), przekazując parametr RectangularBounds. Poniższy przykład kodu pokazuje wywołanie funkcji setLocationRestriction() w instancji fragmentu, aby dostosować sugestie autouzupełniania do regionu Sydney w Australii.

Kotlin

        autocompleteFragment.setLocationRestriction(bounds)

      

Java

        autocompleteFragment.setLocationRestriction(
                RectangularBounds.newInstance(
                        new LatLng(-33.880490, 151.184363),
                        new LatLng(-33.858754, 151.229596)
                )
        );

      

Uwaga: to ograniczenie jest stosowane tylko do całych tras. Wyniki syntetyczne znajdujące się poza prostokątnymi granicami mogą być zwracane na podstawie trasy, która pokrywa się z ograniczeniem lokalizacji.

Filtrowanie wyników według typów miejsc lub kolekcji typów

Możesz ograniczyć wyniki żądania autouzupełniania, aby zwracały tylko określony typ miejsca. Określ filtr, używając typów miejsc lub kolekcji typów wymienionych w tabelach 1, 2 i 3 na stronie Typy miejsc. Jeśli nic nie zostanie określone, zwracane są wszystkie typy.

Aby filtrować wyniki autouzupełniania, wywołaj setTypesFilter() w celu ustawienia filtra.

Aby określić filtr typu lub kolekcji typów:

• Wywołaj setTypesFilter() i określ maksymalnie 5 wartości typu z tabeli 1 i tabeli 2 na stronie Typy miejsc. Wartości typu są zdefiniowane przez stałe w PlaceTypes.

• Wywołaj setTypesFilter() i określ kolekcję typów z tabeli 3 na stronie Typy miejsc. Wartości kolekcji są zdefiniowane przez stałe w PlaceTypes.

  W żądaniu dozwolony jest tylko jeden typ z tabeli 3. Jeśli określisz wartość z tabeli 3, nie możesz określić wartości z tabeli 1 ani 2. Jeśli tak zrobisz, wystąpi błąd.

Poniższy przykład kodu wywołuje setTypesFilter() na obiekcie AutocompleteSupportFragment i określa wiele wartości typu.

Kotlin

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

      

Java

    autocompleteFragment.setTypesFilter(List.of("landmark", "restaurant", "store"));

      

Poniższy przykład kodu pokazuje wywołanie funkcji setTypesFilter() na obiekcie AutocompleteSupportFragment w celu ustawienia filtra zwracającego tylko wyniki z dokładnym adresem przez określenie kolekcji typów.

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java

    autocompleteFragment.setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT));

      

Poniższy przykład kodu pokazuje wywołanie funkcji setTypesFilter() na obiekcie IntentBuilder w celu ustawienia filtra zwracającego tylko wyniki z dokładnym adresem przez określenie kolekcji typów.

Kotlin

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ESTABLISHMENT))
        .build(this)

      

Java

    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(List.of(PlaceTypes.ESTABLISHMENT))
            .build(this);

      

Filtrowanie wyników według kraju

Aby filtrować wyniki autouzupełniania do maksymalnie 5 krajów, wywołaj setCountries() w celu ustawienia kodu kraju. Następnie przekaż filtr do fragmentu lub intencji. Kraje muszą być przekazywane jako dwuznakowy kod kraju zgodny ze standardem ISO 3166-1 Alpha-2.

Poniższy przykład kodu pokazuje wywołanie funkcji setCountries() na obiekcie AutocompleteSupportFragment w celu ustawienia filtra zwracającego tylko wyniki z określonych krajów.

Kotlin

    autocompleteFragment.setCountries("AU", "NZ")

      

Java

    autocompleteFragment.setCountries("AU", "NZ");

      

Limity wykorzystania

Korzystanie z interfejsu Places API (starszego), w tym z pakietu Places SDK na Androida (starszego), nie jest już ograniczone do maksymalnej liczby żądań dziennie (QPD). Obowiązują jednak te limity wykorzystania:

• Limit to 6000 zapytań na minutę. Jest ona obliczana jako suma żądań po stronie klienta i po stronie serwera dla wszystkich aplikacji korzystających z danych logowania tego samego projektu.

Wyświetlanie atrybucji w aplikacji

• Jeśli aplikacja korzysta z usługi autouzupełniania programowo, interfejs użytkownika musi wyświetlać atrybucję „Powered by Google” lub pojawiać się na mapie oznaczonej marką Google.
• Jeśli Twoja aplikacja korzysta z widżetu autouzupełniania, nie musisz podejmować żadnych dodatkowych działań (wymagane atrybucje są wyświetlane domyślnie).
• Jeśli po pobraniu miejsca według identyfikatora pobierzesz i wyświetlisz dodatkowe informacje o miejscu, musisz też wyświetlić atrybucje innych firm.

Więcej informacji znajdziesz w dokumentacji dotyczącej atrybucji.

Optymalizacja Autouzupełniania miejsc (starsza wersja)

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

Oto kilka ogólnych wskazówek:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania miejsc (starszego) w Maps JavaScript API, widżetu autouzupełniania miejsc (starszego) w pakiecie SDK Miejsc na Androida lub elementu sterującego interfejsu autouzupełniania miejsc (starszego) w pakiecie SDK Miejsc na iOS.
• Poznaj najważniejsze pola danych Autouzupełniania miejsc (starsza wersja) 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.
• 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ć koszt korzystania z usługi autouzupełniania miejsc (starszej wersji), używaj masek pól w widżetach informacji o miejscu (starszej wersji) i autouzupełniania miejsc (starszej wersji), aby zwracać tylko potrzebne pola danych autouzupełniania miejsc (starszej wersji).

Zaawansowana optymalizacja kosztów

Rozważ programowe wdrożenie usługi Autouzupełnianie miejsc (starsza wersja), aby uzyskać dostęp do SKU: Autouzupełnianie – cena za żądanie i zamiast informacji o miejscu (starsza wersja) wysyłać żądania wyników interfejsu Geocoding API dotyczących wybranego miejsca. Cena za żądanie w połączeniu z interfejsem Geocoding API jest bardziej opłacalna niż cena za sesję (oparta na sesji), 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 (starszego).
• Jeśli użytkownicy wybiorą podpowiedź autouzupełniania w ramach średnio 4 lub mniej żądań Autouzupełniania miejsc (starsza wersja), cena za żądanie może być bardziej opłacalna niż cena za sesję.

Aby uzyskać pomoc w wyborze implementacji Autouzupełniania miejsc (starszej wersji), która odpowiada Twoim potrzebom, wybierz kartę odpowiadającą Twojej odpowiedzi na to pytanie.

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

Tak, potrzebne są bardziej szczegółowe informacje

Używaj Autouzupełniania miejsc opartego na sesji (starsza wersja) z Informacjami o miejscu (starsza wersja).
Ponieważ Twoja aplikacja wymaga szczegółów miejsca (starsza wersja), takich jak nazwa miejsca, status firmy lub godziny otwarcia, w implementacji autouzupełniania miejsc (starsza wersja) należy używać tokena sesji na sesję (programowo lub wbudowanego w widżety JavaScript, Android lub iOS) oraz odpowiednich kodów SKU danych o miejscach w zależności od tego, o które pola danych o miejscach prosisz.¹

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

Implementacja programowa
Używaj tokena sesji w żądaniach autouzupełniania miejsc (starsza wersja). Podczas wysyłania żądania informacji o miejscu (starsza wersja) dotyczącego wybranej podpowiedzi uwzględnij te parametry:

1. Identyfikator miejsca z odpowiedzi Autouzupełniania miejsc (starszej wersji).
2. Token sesji użyty w żądaniu Autouzupełniania miejsc (starsza wersja).
3. Parametr fields określający pola danych autouzupełniania miejsc (starsza wersja), które są potrzebne.

Nie, wystarczy adres i lokalizacja

W zależności od wydajności korzystania z Autouzupełniania miejsc (starsza wersja) interfejs Geocoding API może być bardziej opłacalną opcją niż informacje o miejscu (starsza wersja). Skuteczność każdej aplikacji korzystającej z funkcji Autouzupełnianie miejsc (starsza wersja) zależy od tego, co wpisują użytkownicy, gdzie jest używana aplikacja i czy zostały wdrożone sprawdzone metody optymalizacji wydajności.

Aby odpowiedzieć na to pytanie, przeanalizuj, ile znaków użytkownik wpisuje średnio, zanim wybierze prognozę autouzupełniania miejsc (starszej wersji) w Twojej aplikacji.

Czy użytkownicy wybierają prognozę autouzupełniania miejsc (starszego) średnio w 4 lub mniejszej liczbie żądań?

Tak

Wdrażaj programowo funkcję autouzupełniania miejsc (starszą wersję) bez tokenów sesji i wywołuj interfejs Geocoding API w przypadku wybranej prognozy miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej. Wysłanie 4 żądań Autouzupełnianie – na żądanie oraz wywołanie interfejsu Geocoding API dotyczące wybranej podpowiedzi miejsca jest tańsze niż koszt sesji Autouzupełnianie miejsc (starsza wersja) na sesję.¹

Aby pomóc użytkownikom uzyskać prognozę, której szukają, nawet przy użyciu mniejszej liczby znaków, rozważ zastosowanie sprawdzonych metod dotyczących wydajności.

Nie

Używaj Autouzupełniania miejsc opartego na sesji (starsza wersja) z Informacjami o miejscu (starsza wersja).
Średnia liczba żądań, które prawdopodobnie wyślesz, zanim użytkownik wybierze prognozę Autouzupełniania miejsc (starszego), przekracza koszt cen za sesję, więc w implementacji Autouzupełniania miejsc (starszego) należy używać tokena sesji zarówno w przypadku żądań Autouzupełniania miejsc (starszego), jak i powiązanego żądania informacji o miejscu (starszego) za sesję. ¹

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

Implementacja programowa
Używaj tokena sesji w żądaniach autouzupełniania miejsc (starsza wersja). Gdy wysyłasz żądanie informacji o miejscu (starsza wersja) dotyczących wybranej podpowiedzi, uwzględnij te parametry:

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

Rozważ opóźnienie żądań autouzupełniania miejsc (starsza wersja)
Możesz zastosować strategie, takie jak opóźnienie żądania autouzupełniania miejsc (starsza wersja), dopóki użytkownik nie wpisze pierwszych 3–4 znaków, aby aplikacja wysyłała mniej żądań. Jeśli na przykład wysyłasz żądania do interfejsu API autouzupełniania miejsc (starszej wersji) dla każdego znaku po wpisaniu przez użytkownika trzeciego znaku, a użytkownik wpisze 7 znaków, a potem wybierze podpowiedź, dla której wysyłasz 1 żądanie do interfejsu Geocoding API, łączny koszt wyniesie 4 żądania do interfejsu API autouzupełniania miejsc (starszej wersji) + geokodowanie.¹

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań programowych będzie mniejsza niż 4, możesz postępować zgodnie z instrukcjami dotyczącymi implementacji wydajnego autouzupełniania miejsc (starszego) 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ć, że prognozy będą wyświetlane po każdym naciśnięciu klawisza.

Aby ułatwić użytkownikom uzyskanie prognozy, której szukają, przy użyciu mniejszej liczby znaków, rozważ zastosowanie sprawdzonych metod dotyczących wydajności.

---

1. Ceny znajdziesz w cennikach Google Maps Platform.

Sprawdzone metody dotyczące wydajności

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

• Dodaj do implementacji funkcji Autouzupełnianie miejsc (starsza wersja) ograniczenia związane z krajem, ustawianie preferencji lokalizacji i (w przypadku implementacji zautomatyzowanych) 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 usługa autouzupełniania miejsc (starsza wersja) jest używana z mapą, możesz określić lokalizację na podstawie widocznego obszaru mapy.
• W sytuacjach, gdy użytkownik nie wybierze żadnej z podpowiedzi Autouzupełniania miejsc (starsza wersja), zwykle dlatego, że żadna z nich nie jest adresem, którego szuka, możesz ponownie użyć pierwotnych danych wejściowych użytkownika, aby uzyskać trafniejsze wyniki:
  • Jeśli oczekujesz, że użytkownik poda 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 informacje o miejscu (starsza wersja). Jeśli wyniki mają być wyświetlane tylko w określonym regionie, użyj ustawienia lokalizacji.
  Inne scenariusze, w których warto wrócić do Geocoding API, to:
  • 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” daje częściową podpowiedź w usłudze Autouzupełnianie miejsc (starsza 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. Ta wartość informuje usługę Autouzupełnianie miejsc (starsza wersja), ż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 includedRegionCodes, aby filtrować wyniki i wyświetlać tylko miejsca w określonym kraju.

Ostrzeżenie: jeśli nie podasz wartości radius, parametr location zostanie zignorowany.

Wyniki dotyczące placówek zwykle nie mają wystarczająco wysokiej pozycji, aby wyświetlać się w wynikach, gdy obszar wyszukiwania jest duży. Jeśli chcesz, aby obiekty pojawiały się w wynikach mieszanych (obiekty i kody pocztowe), możesz określić mniejszy promień. Możesz też użyć types=establishment, aby ograniczyć wyniki tylko do placówek.

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 strictbounds. To polecenie nakazuje interfejsowi Autouzupełnianie miejsc (starsza wersja) zwracanie tylko wyników w tym regionie.

Uwaga: ograniczenia lokalizacji są stosowane tylko do całych tras. Wyniki syntetyczne znajdujące się poza ograniczeniem lokalizacji mogą być zwracane na podstawie trasy, która pokrywa się z ograniczeniem lokalizacji.

Rozwiązywanie problemów

Może wystąpić wiele różnych błędów, ale większość z nich jest zwykle spowodowana błędami konfiguracji (np. użyto nieprawidłowego klucza API lub klucz API został nieprawidłowo skonfigurowany) lub błędami związanymi z limitem (aplikacja przekroczyła limit). Więcej informacji o limitach znajdziesz w sekcji Limity wykorzystania.

Błędy, które wystąpią podczas korzystania z elementów sterujących autouzupełniania, są zwracane w wywołaniu zwrotnym onActivityResult(). Wywołaj funkcję Autocomplete.getStatus(), aby uzyskać komunikat o stanie wyniku.