Autouzupełnianie miejsc (starsza wersja)

Deweloperzy z Europejskiego Obszaru Gospodarczego (EOG)

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.

Autouzupełnianie możesz dodać do aplikacji na te sposoby:

Dodawanie widżetu autouzupełniania

Widżet autouzupełniania to okno wyszukiwania z wbudowaną funkcją autouzupełniania. Gdy użytkownik wpisuje wyszukiwane słowa, widżet wyświetla listę przewidywanych miejsc do wyboru. Gdy użytkownik dokona wyboru, zwracane jest wystąpienie Place, którego 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ść 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, umieść fragment w innym elemencie układu, takim jak 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 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.

Aby uruchomić widżet autouzupełniania za pomocą intencji, wykonaj te czynności:

  1. Użyj Autocomplete.IntentBuilder, aby utworzyć intencję, przekazując odpowiedni tryb Autocomplete.
  2. Zdefiniuj program uruchamiający wyniki aktywności registerForActivityResult, którego można użyć do uruchomienia intencji i obsługi wybranej przez użytkownika prognozy miejsca w wyniku.

Tworzenie intencji autouzupełniania

W przykładzie poniżej użyto Autocomplete.IntentBuilder, aby utworzyć intencję uruchomienia widżetu autouzupełniania jako intencji:

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

Gdy używasz intencji do uruchomienia widżetu autouzupełniania, możesz wybrać tryb wyświetlania nakładki lub pełnego ekranu. Zrzuty ekranu poniżej pokazują poszczególne tryby wyświetlania:

Gdy widżet autouzupełniania jest wyświetlany w trybie nakładki, pojawia się on na interfejsie wywołującym.
Rysunek 1. Widżet autouzupełniania w trybie OVERLAY
Gdy widżet autouzupełniania jest wyświetlany w trybie pełnoekranowym, zajmuje cały ekran.
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 program uruchamiający registerForActivityResult(), który uruchamia aktywność i obsługuje wynik, jak 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");
            }
        });

Uzyskiwanie podpowiedzi miejsc w sposób zautomatyzowany

Możesz utworzyć niestandardowy interfejs wyszukiwania jako alternatywę dla interfejsu udostępnianego przez widżet autouzupełniania. Aby to zrobić, aplikacja musi pobierać prognozy miejsc automatycznie. Aplikacja może uzyskać 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: AutocompleteSessionToken, który grupuje fazy zapytania i wyboru wyszukiwania 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 alfa-2) wskazujący kraj lub kraje, do których należy ograniczyć wyniki.

  • Opcjonalnie: 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ć nieokreślona.
    • TypeFilter.ADDRESS – zwraca tylko wyniki autouzupełniania z dokładnym adresem. Używaj tego typu, gdy wiesz, że użytkownik szuka w pełni określonego 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: LatLng określający lokalizację źródła żą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 metody 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 ramach Task. Obiekt 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 prognozowanego miejsca możesz wywołać te metody, aby pobrać szczegółowe informacje o miejscu:

  • getFullText(CharacterStyle) zwraca pełny tekst opisu miejsca. To połączenie tekstu głównego i dodatkowego. Przykład: „Wieża Eiffla, Avenue Anatole France, Paryż, Francja”. Dodatkowo ta metoda pozwala wyróżnić sekcje opisu, które pasują do wyszukiwania, za pomocą wybranego stylu, używając CharacterStyle. Parametr CharacterStyle jest opcjonalny. Jeśli nie chcesz wyróżniać tekstu, ustaw wartość null.
  • getPrimaryText(CharacterStyle) zwraca główny tekst opisujący miejsce. Zwykle jest to nazwa miejsca. Przykłady: „Wieża Eiffla” i „ul. Krótka 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 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.

Tokeny sesji

Tokeny sesji grupują etapy zapytania i wyboru wyszukiwania z autouzupełnianiem przez użytkownika w osobną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy, gdy wybiera miejsce. Każda sesja może zawierać wiele zapytań, po których następuje wybór jednego miejsca. Po zakończeniu sesji token traci ważność. Aplikacja musi generować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji we wszystkich sesjach autouzupełniania wywoływanych automatycznie (gdy umieszczasz fragment lub uruchamiasz autouzupełnianie za pomocą intencji, interfejs API zajmuje się tym automatycznie).

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 metody fetchPlace(), aby pobrać informacje o miejscu wybranego przez użytkownika.

Więcej informacji o tokenach sesji

Ograniczanie wyników autouzupełniania

Możesz ograniczyć wyniki autouzupełniania do określonego regionu geograficznego lub przefiltrować je według co najmniej jednego typu miejsca albo maksymalnie 5 krajów. Te ograniczenia możesz stosować do aktywności autouzupełniania, AutocompleteSupportFragment i interfejsów API do automatycznego uzupełniania.

Aby ograniczyć wyniki:

  • Aby preferować wyniki w określonym regionie, wywołaj setLocationBias() (mogą być nadal zwracane niektóre wyniki spoza określonego regionu).
  • Aby wyświetlać tylko wyniki z określonego regionu, wywołaj setLocationRestriction() (zwracane będą tylko wyniki z określonego regionu).
  • Aby zwracać tylko wyniki zgodne z określonym typem miejsca, wywołaj setTypesFilter() (np. podanie 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.

Wpływanie na wyniki w określonym regionie

Aby ukierunkować wyniki autouzupełniania na określony region geograficzny, wywołaj setLocationBias(), przekazując RectangularBounds. Poniższy przykładowy kod pokazuje wywołanie metody setLocationBias() w instancji fragmentu, aby zawęzić 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)
                )
        );

Ogranicz wyniki do konkretnego regionu

Aby ograniczyć wyniki autouzupełniania do określonego regionu geograficznego, wywołaj funkcję setLocationRestriction(), przekazując obiekt 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, tak 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 określisz, 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 podaj maksymalnie 5 wartości type z tabeli 1 i 2 widocznych w sekcji Typy miejsc. Wartości typu są zdefiniowane przez stałe w PlaceTypes.

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

    W żądaniu dozwolony jest tylko 1 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 to zrobisz, wystąpi błąd.

Poniższy przykładowy kod wywołuje metodę 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ładowy kod pokazuje wywołanie setTypesFilter() w AutocompleteSupportFragment, aby ustawić filtr zwracający 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(), aby ustawić kod kraju. Następnie przekaż filtr do fragmentu lub intencji. Kraje muszą być przekazywane jako dwuznakowy kod kraju zgodny ze standardem ISO 3166-1 alfa-2.

Poniższy przykładowy kod pokazuje wywołanie setCountries() na AutocompleteSupportFragment, aby ustawić filtr zwracający tylko wyniki w określonych krajach.

Kotlin

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

Java

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

Limity wykorzystania

Korzystanie z interfejsu Places API (starsza wersja), w tym z pakietu Places SDK for Android (starsza wersja), nie jest już ograniczone do maksymalnej liczby żądań dziennie. Nadal obowiązują jednak te limity wykorzystania:

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

Wyświetlanie atrybucji w aplikacji

  • Jeśli Twoja aplikacja korzysta z usługi autouzupełniania automatycznie, interfejs musi wyświetlać atrybucję „Powered by Google” lub pojawiać się na mapie z logo 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ć informacje o autorze pochodzące od 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łniania miejsc (starszej wersji).

Oto ogólne wskazówki:

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszty korzystania z usługi Autouzupełnianie miejsc (starsza wersja), użyj masek pól w widżetach Informacje o miejscu (starsza wersja) i Autouzupełnianie miejsc (starsza wersja), aby zwracać tylko te pola danych Autouzupełniania miejsc (starsza wersja), których potrzebujesz.

Zaawansowana optymalizacja kosztów

Rozważ programowe wdrożenie Autouzupełniania miejsc (starsza wersja), aby uzyskać dostęp do SKU: Autouzupełnianie – cena za żądanie i poprosić o wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast informacji o miejscu (starsza wersja). 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 użytkownika, Geocoding API dostarczy te informacje za niższą cenę niż wywołanie Place Details (Legacy).
  • Jeśli użytkownicy wybierają podpowiedź autouzupełniania średnio w ciągu maksymalnie 4 żądań podpowiedzi autouzupełniania miejsc (starsza wersja), ceny za żądanie mogą być bardziej opłacalne niż ceny za sesję.
Aby wybrać implementację Autouzupełniania miejsc (starszej wersji), która odpowiada Twoim potrzebom, kliknij kartę odpowiadającą Twojej odpowiedzi na to pytanie.

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

Tak, potrzebuję więcej informacji

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

Wdrożenie widżetu
Zarządzanie sesjami 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 tych pól danych autouzupełniania miejsc (starsza wersja), których potrzebujesz.

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

  1. Identyfikator miejsca z odpowiedzi Autouzupełniania miejsc (starsza wersja).
  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, potrzebuje tylko adresu i lokalizacji

W zależności od skuteczności korzystania z interfejsu Autouzupełnianie miejsc (starszego) interfejs Geocoding API może być bardziej opłacalną opcją niż interfejs informacje o miejscu (starszy). Skuteczność autouzupełniania miejsc (starszej wersji) w każdej aplikacji zależy od tego, co wpisują użytkownicy, gdzie aplikacja jest używana i czy wdrożono sprawdzone metody optymalizacji wydajności.

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

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

Tak

Zaimplementuj programowo Autouzupełnianie miejsc (starsza wersja) bez tokenów sesji i wywołaj interfejs Geocoding API w przypadku wybranej podpowiedzi miejsca.
Geocoding API udostępnia adresy oraz współrzędne szerokości i długości geograficznej. Wykonanie 4 żądań Autouzupełnianie – na żądanie oraz wywołania Geocoding API dotyczącego wybranej podpowiedzi miejsca kosztuje mniej niż Autouzupełnianie miejsc (starsza wersja) na sesję.1

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

Nie

Używaj autouzupełniania miejsc (starsza wersja) opartego na sesjach z informacjami o miejscu (starsza wersja).
Ponieważ średnia liczba żądań, które spodziewasz się wysłać, zanim użytkownik wybierze podpowiedź Autouzupełniania miejsc (starsza wersja), przekracza koszt ceny za sesję, Twoja implementacja Autouzupełniania miejsc (starsza wersja) powinna używać tokena sesji zarówno w przypadku żądań Autouzupełniania miejsc (starsza wersja), jak i powiązanych żądań informacji o miejscu (starsza wersja) za sesję. 1

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). Wysyłając żądanie informacji o miejscu (starsza wersja) dotyczące 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 (starszego)
  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 lub 4 znaków, dzięki czemu aplikacja będzie wysyłać mniej żądań. Jeśli na przykład wysyłasz żądania Place Autocomplete (Legacy) dla każdego znaku po wpisaniu przez użytkownika trzeciego znaku, oznacza to, że jeśli użytkownik wpisze 7 znaków, a następnie wybierze podpowiedź, dla której wysyłasz jedno żądanie do interfejsu Geocoding API, łączny koszt będzie obejmował 4 żądania Place Autocomplete (Legacy) i żądanie do interfejsu Geocoding1.

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań zautomatyzowanych spadnie poniżej 4, możesz postępować zgodnie z instrukcjami dotyczącymi implementacji wydajnego interfejsu Autouzupełnianie miejsc (starsza wersja) 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 po każdym naciśnięciu klawisza zobaczy prognozy.

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby pomóc użytkownikom uzyskać oczekiwane podpowiedzi przy użyciu mniejszej liczby znaków.

  1. Koszty znajdziesz w cennikach Google Maps Platform.

Sprawdzone metody dotyczące wydajności

W poniższych wytycznych opisano sposoby optymalizacji skuteczności usługi Autouzupełnianie miejsc (starsza wersja):

  • Dodaj do implementacji Autouzupełniania miejsc (starszej wersji) ograniczenia związane z krajem, ustawienia lokalizacji i (w przypadku implementacji automatycznych) preferencje językowe. Ustawienia języka nie są potrzebne w przypadku widżetów, ponieważ pobierają one ustawienia języka z przeglądarki lub urządzenia mobilnego użytkownika.
  • Jeśli autouzupełnianiu miejsc (starsza wersja) towarzyszy mapa, możesz określić lokalizację na podstawie widocznego obszaru mapy.
  • W sytuacjach, gdy użytkownik nie wybierze żadnej z prognoz 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 spróbować uzyskać trafniejsze wyniki:
    • Jeśli oczekujesz, że użytkownik wpisze tylko informacje o adresie, użyj ponownie oryginalnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
    • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania informacji o miejscu (starsza wersja). Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj ustawiania lokalizacji.
    Inne sytuacje, 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” zwraca 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

Możesz faworyzować wyniki z określonego obszaru, przekazując parametry location i radius. Dzięki temu Autouzupełnianie miejsc (starsza wersja) będzie 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 strictbounds. Dzięki temu Autouzupełnianie miejsc (starsza wersja) zwraca tylko wyniki z tego regionu.

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 interfejsu API lub klucz interfejsu 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ły podczas korzystania z elementów sterujących autouzupełniania, są zwracane w wywołaniu zwrotnym onActivityResult(). Wywołaj Autocomplete.getStatus(), aby uzyskać komunikat o stanie wyniku.