Autouzupełnianie miejsc

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Usługa autouzupełniania w pakiecie SDK Miejsc na Androida zwraca odpowiedzi na zapytania użytkowników. Jako typ użytkownika usługa autouzupełniania zwraca sugestie miejsc, takich jak firmy, adresy, kody Plus Code i ciekawe miejsca.

Autouzupełnianie możesz dodać do aplikacji na kilka sposobów:

Dodawanie widżetu autouzupełniania

Widżet autouzupełniania to okno wyszukiwania z wbudowanymi funkcjami autouzupełniania. Gdy użytkownik wpisze wyszukiwane hasło, widżet wyświetla listę przewidywanych miejsc do wyboru. Gdy użytkownik dokona wyboru, zostanie zwrócona instancja Place, której aplikacja może użyć do uzyskania szczegółowych informacji o wybranym miejscu.

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

Opcja 1. Umieść fragment autouzupełnianiaObsługiwane

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

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

Dodawanie AutocompleteSupportFragment do aktywności

Aby dodać do aktywności element AutocompleteSupportFragment, dodaj nowy fragment do układu XML. 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, takim jak CardView.
  • Jeśli używasz fragmentu autouzupełniania i musisz zastąpić tekst onActivityResult, musisz wywołać metodę super.onActivityResult. W przeciwnym razie fragment nie będzie działać prawidłowo.

Dodawanie elementu PlaceSelectionListener do aktywności

PlaceSelectionListener obsługuje zwracanie miejsca w odpowiedzi na wybór użytkownika. Ten kod pokazuje, jak utworzyć odwołanie do fragmentu i dodać detektor do AutocompleteSupportFragment:

Java


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

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

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.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

Opcja 2. Użyj intencji uruchamiania autouzupełniania

Jeśli chcesz, aby aplikacja korzystała z innego sposobu nawigacji (na przykład do aktywowania autouzupełniania przy użyciu ikony, a nie pola wyszukiwania), może ona uruchamiać autouzupełnianie, korzystając z intencji.

Aby uruchomić widżet autouzupełniania z intencją:

  1. Utwórz intencję Autocomplete.IntentBuilder, przekazując odpowiedni tryb Autocomplete. Intencja musi wywołać metodę startActivityForResult, przekazując kod żądania, który ją identyfikuje.
  2. Zastąp wywołanie zwrotne onActivityResult, aby otrzymać wybrane miejsce.

Tworzenie intencji autouzupełniania

Przykład poniżej pokazuje użycie Autocomplete.IntentBuilder do utworzenia intencji uruchamiania autouzupełniania jako intencji:

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

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

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

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

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

Jeśli chcesz włączyć widżet autouzupełniania, masz do wyboru tryby nakładki lub pełnego ekranu. Poniższe zrzuty ekranu pokazują każdy tryb wyświetlania:

W trybie nakładki widżet autouzupełniania jest wyświetlany na interfejsie użytkownika.
Ilustracja 1. Autouzupełnianie widżetu w trybie Nakładki
Widżet autouzupełniania wyświetla cały ekran, gdy wyświetla się w trybie pełnoekranowym.
Ilustracja 2. Autouzupełnianie widżetu w trybie PEŁNYM

Zastąp wywołanie zwrotne onActivityResult

Aby otrzymać powiadomienie o wybraniu miejsca przez użytkownika, aplikacja powinna zastąpić onActivityResult() aktywności, wyszukując kod żądania przekazany zgodnie z intencją, jak widać w poniższym przykładzie.

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

Automatyczne prognozowanie miejsc

Zamiast interfejsu udostępnianego przez widżet autouzupełniania możesz utworzyć własny interfejs wyszukiwania. Aby to umożliwić, aplikacja musi prognozować miejsca automatycznie. Aplikacja może pobrać listę prognozowanych nazw miejsc lub adresów z interfejsu autouzupełniania API, wywołując interfejs PlacesClient.findAutocompletePredictions() i przekazując obiekt FindAutocompletePredictionsRequest z tymi parametrami:

  • Wymagane: ciąg query zawierający tekst wpisany przez użytkownika.
  • Zalecane: AutocompleteSessionToken, które grupuje zapytanie i wybory użytkowników w określonych sesjach na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierze miejsce.
  • Zalecane: obiekt RectangularBounds, który określa ograniczenia szerokości i długości geograficznej w celu ograniczenia wyników do określonego regionu.
  • Opcjonalnie: co najmniej 1-literowy kod kraju (ISO 3166-1 alfa-2) wskazujący kraj, do którego 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. Prześlij prośbę o określenie wyników, w których przypadku 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 te miejsca, które są firmami.
    • TypeFilter.REGIONS – zwraca tylko te 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ąc lokalizację punktu początkowego żądania. Gdy wywołujesz właściwość setOrigin(), dla każdej podpowiedzi autouzupełniania w odpowiedzi usługa zwraca dystans w metrach (distanceMeters).

Informacje o typach miejsc znajdziesz w przewodniku po typach miejsc.

Przykład poniżej pokazuje pełne wywołanie PlacesClient.findAutocompletePredictions().

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(Arrays.asList(TypeFilter.ADDRESS.toString()))
        .setSessionToken(token)
        .setQuery(query)
        .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

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(TypeFilter.ADDRESS.toString()))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: " + exception.statusCode)
            }
        }

      

Interfejs API zwraca błąd FindAutocompletePredictionsResponse w obiekcie Task. FindAutocompletePredictionsResponse zawiera listę obiektów AutocompletePrediction reprezentujących przewidywane miejsca. Jeśli lista nie pasuje do zapytania ani kryteriów filtrowania, lista może być pusta.

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 głównego i dodatkowego. Przykład: „Wieża Eiffla, Aleja Francuska, Paryż, Francja”. Oprócz tego ta metoda pozwala wyróżnić sekcje tekstu, które pasują do wyszukiwania za pomocą wybranego stylu, i użyć 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: „Eiffel Tower” i „123 Pitt Street”.
  • getSecondaryText(CharacterStyle) zwraca opis podmiotu zależnego. Jest to przydatne na przykład jako drugi wiersz podczas wyświetlania podpowiedzi autouzupełniania. Przykłady: „Avenue Anatole France, Paris, France” i „Sydney, Nowa Południowa Walia”.
  • getPlaceId() zwraca identyfikator miejsca przewidywanego. Identyfikator miejsca to tekstowy identyfikator, który jednoznacznie identyfikuje miejsce i można go później użyć do ponownego pobrania obiektu Place. Więcej informacji o identyfikatorach miejsc w pakiecie Miejsc na Androida znajdziesz w artykule Szczegóły miejsca. Ogólne informacje o identyfikatorach miejsc znajdziesz w artykule Omówienie identyfikatorów miejsc.
  • getPlaceTypes() zwraca listę typów miejsc powiązanych z tym miejscem.
  • getDistanceMeters() zwraca odległość w metrach prostych między miejscem a punktem początkowym podanym w żądaniu.

Tokeny sesji

Tokeny sesji grupują fazę zapytania i wyboru podczas autouzupełniania wyszukiwania użytkownika w oddzielną sesję na potrzeby płatności. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierze miejsce. Każda sesja może mieć wiele zapytań, po których następuje jedno wybranie miejsca. Po zakończeniu sesji token jest już nieważny. Aplikacja musi wygenerować nowy token dla każdej sesji. Zalecamy korzystanie z tokenów sesji w przypadku wszystkich zautomatyzowanych sesji autouzupełniania (gdy umieścisz fragment kodu lub uruchomisz autouzupełnianie zgodnie z intencją, interfejs API zajmie się tym automatycznie).

Pakiet SDK Miejsc na Androida używa identyfikatora AutocompleteSessionToken do identyfikowania każdej sesji. Aplikacja powinna przekazać nowy token sesji po rozpoczęciu każdej nowej sesji, a potem przekazać ten sam token wraz z identyfikatorem miejsca w kolejnym wywołaniu funkcji fetchPlace(), by pobrać szczegóły miejsca wybranego przez użytkownika.

Więcej informacji o tokenach sesji

Blokowanie wyników autouzupełniania

Możesz ograniczyć wyniki autouzupełniania do określonego regionu geograficznego lub filtrować je według jednego lub większej liczby typów miejsc albo do maksymalnie 5 krajów. Te ograniczenia możesz zastosować do aktywności autouzupełniania, w AutocompleteSupportFragment i przy użyciu interfejsów API autouzupełniania.

Aby ograniczyć wyniki, wykonaj te czynności:

  • Aby preferować wyniki w określonym regionie, wywołaj setLocationBias() (niektóre wyniki spoza zdefiniowanego regionu mogą być zwracane).
  • Aby pokazać tylko wyniki ze wskazanego regionu, wywołaj setLocationRestriction(). Zostaną zwrócone tylko wyniki ze wskazanego regionu.
  • Aby wyświetlić tylko wyniki pasujące do określonego typu miejsca, wywołaj metodę setTypesFilter() (np. określenie ciągu TypeFilter.ADDRESS spowoduje wyświetlenie tylko wyników z dokładnym adresem).
  • Aby wyświetlić wyniki tylko w maksymalnie 5 wybranych krajach, zadzwoń pod numer setCountries(). Kraje muszą być przekazywane jako dwuznakowy kod kraju zgodny ze standardem ISO 3166-1 alfa-2.

Wyniki wyszukiwania w konkretnym regionie

Aby stronnić wyniki autouzupełniania dla określonego regionu geograficznego, wywołaj setLocationBias() i prześlij RectangularBounds. Poniższy przykładowy kod pokazuje wywoływanie funkcji setLocationBias() w odniesieniu do fragmentu kodu, aby wskazać na niego sugestię autouzupełniania dla regionu Sydney w Australii.

Java


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

      

Kotlin


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

      

Ogranicza wyniki do określonego regionu

Aby ograniczyć wyniki autouzupełniania do określonego regionu geograficznego, wywołaj metodę setLocationRestriction() i przekaż RectangularBounds. Poniższy przykładowy kod pokazuje wywołanie setLocationRestriction() w instancji fragmentu, aby wskazać na niego sugestie autouzupełniania dla regionu Sydney w Australii.

Java


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

      

Kotlin


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

      

Uwaga: to ograniczenie dotyczy tylko całych tras, wyniki syntetyczne umieszczone poza granicami prostokątnymi mogą być zwracane na podstawie trasy pokrywającej się z ograniczeniem lokalizacji.

Filtruj wyniki według typu miejsca lub kolekcji typów

Możesz ograniczyć wyniki z żądania autouzupełniania, tak aby zwracały tylko określony typ miejsca. Określ filtr, korzystając z typów miejsc lub kolekcji typów wymienionych w tabelach 1, 2 i 3 w sekcji Typy miejsc. Jeśli nie określisz żadnej wartości, zostaną zwrócone wszystkie typy.

Aby filtrować wyniki autouzupełniania, wywołaj metodę setTypesFilter().

Aby określić filtr typu lub typu kolekcji:

  • Wywołaj setTypesFilter() i określ maksymalnie 5 wartości typu wyświetlanych z tabeli 1 i 2 w tabeli Typy miejsc. Wartości typów definiuje się na podstawie stałych w PlaceTypes.

  • Wywołaj setTypesFilter() i określ kolekcję typów z tabeli 3 widoczną w sekcji Typy miejsc. Wartości kolekcji definiuje się na podstawie stałych w PlaceTypes.

    W żądaniu można użyć tylko jednego typu z tabeli 3. Jeśli podasz wartość z tabeli 3, nie możesz podać wartości z tabeli 1 lub 2. Jeśli to zrobisz, wystąpi błąd.

Ten przykładowy kod wywołuje metodę setTypesFilter() na AutocompleteSupportFragment i określa wiele wartości typu.

Java


    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

Kotlin


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

      

Poniższy przykładowy kod pokazuje wywołanie setTypesFilter() na AutocompleteSupportFragment, aby ustawić filtr zwracający tylko wyniki z dokładnym adresem poprzez określenie kolekcji typów.

Java


    autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));

      

Kotlin


    autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))

      

Poniższy przykładowy kod pokazuje wywołanie setTypesFilter() na IntentBuilder, aby ustawić filtr zwracający tylko wyniki z dokładnym adresem poprzez określenie kolekcji typów.

Java


    Intent intent = new Autocomplete.IntentBuilder(
        AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()))
        .build(this);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

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 przekazać filtr do fragmentu kodu 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 z określonych krajów.

Java


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

      

Kotlin


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

      

Limity wykorzystania

Możliwość korzystania z interfejsu Places API (w tym z pakietu SDK do aplikacji na Androida) nie jest ograniczona do maksymalnej dziennej liczby żądań (QPD). Nadal obowiązują jednak te limity wykorzystania:

  • Limit szybkości to 100 żądań na sekundę (QPS). Jest to suma żądań po stronie klienta i po stronie serwera dla wszystkich aplikacji korzystających z danych logowania tego samego projektu.

Wyświetlaj informacje o atrybucji w swojej aplikacji

  • Jeśli Twoja aplikacja korzysta z usługi autouzupełniania, w interfejsie użytkownika musi się znajdować atrybucja oparta na technologii Google lub może ona być widoczna na mapie marki Google.
  • Jeśli aplikacja korzysta z widżetu autouzupełniania, nie są wymagane żadne dodatkowe działania (domyślnie wymagana jest atrybucja).
  • Jeśli po otrzymaniu miejsca na podstawie identyfikatora pobierasz i wyświetlasz dodatkowe informacje o miejscu, musisz też wyświetlić informacje o jego autorach.

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

Optymalizacja autouzupełniania miejsc

Ta sekcja zawiera sprawdzone metody, które pomogą Ci jak najlepiej wykorzystać możliwości autouzupełniania miejsc.

Oto kilka ogólnych wskazówek:

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszt korzystania z usługi autouzupełniania miejsc, użyj masek pól w informacjach o miejscu i autouzupełnianiu miejsc, aby zwracać tylko potrzebne pola danych miejsc.

Zaawansowana optymalizacja kosztów

Rozważ zautomatyzowaną implementację autouzupełniania miejsc, aby uzyskać dostęp do cen za żądanie i poprosić o wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast szczegółów miejsca. Cennik za żądanie w połączeniu z interfejsem Geocoding API jest bardziej opłacalny niż w przypadku sesji (na podstawie sesji) w przypadku, gdy spełnione są oba te warunki:

  • Jeśli potrzebujesz tylko szerokości i długości geograficznej lub adresu wybranego miejsca użytkownika, interfejs Geocoding API udostępnia te informacje w przypadku mniejszej liczby wywołań miejsca.
  • Jeśli użytkownicy wybiorą podpowiedź autouzupełniania, która nie przekracza średnio 4 żądań podpowiedzi autouzupełniania, model cenowy według żądania może być bardziej opłacalny niż określanie stawek na sesję.
Aby uzyskać pomoc przy wyborze implementacji autouzupełniania, która odpowiada Twoim potrzebom, kliknij kartę odpowiadającą odpowiedzi na poniższe pytanie.

Czy zgłoszenie wymaga podania informacji innych niż adres i szerokość lub szerokość geograficzna wybranej prognozy?

Tak, chcę dowiedzieć się więcej

Korzystaj z autouzupełniania miejsc opartych na sesjach ze szczegółami miejsca.
Twoje zgłoszenie wymaga szczegółów dotyczących miejsca, takich jak nazwa miejsca, stan firmy lub godziny otwarcia, dlatego implementacja autouzupełniania miejsc powinna używać tokena sesji (automatycznego lub wbudowanego w widżety JavaScript, Androida lub iOS) o łącznej cenie 0,017 USD za sesję i odpowiednich kodów SKU miejsc1..

Implementacja widżetów
Zarządzanie sesjami jest wbudowane w widżety
JavaScript, Androida lub iOS. Obejmuje to prośby o autouzupełnianie miejsc i żądania szczegółów miejsca dotyczące wybranej prognozy. Pamiętaj, aby określić parametr fields, aby mieć pewność, że wysyłasz tylko wymagane pola danych miejsca.

Automatyzacja implementacji
Użyj tokena sesji w żądaniach autouzupełniania miejsc. Podczas wysyłania prośby o szczegóły miejsca związane z wybraną prognozą podaj te parametry:

  1. Identyfikator miejsca podany w odpowiedzi miejsca autouzupełniania.
  2. Token sesji używany w żądaniu autouzupełniania miejsc
  3. Parametr fields określający pola danych miejsca, których potrzebujesz.

Nie, wystarczy tylko adres i lokalizacja

Interfejs Geocoding API może być bardziej ekonomicznym rozwiązaniem niż szczegółowe informacje o miejscu w aplikacji, w zależności od wydajności korzystania z autouzupełniania miejsc. Efektywność autouzupełniania w poszczególnych aplikacjach zależy od danych wprowadzanych przez użytkowników, miejsc, w których jest używana, oraz od tego, czy zostały zastosowane sprawdzone metody optymalizacji wydajności.

Aby odpowiedzieć na to pytanie, sprawdź, ile znaków średnio wpisuje użytkownik przed wybraniem podpowiedzi autouzupełniania miejsc w Twojej aplikacji.

Czy użytkownicy wybierają średnio podpowiedzi autouzupełniania miejsc w maksymalnie 4 prośbach?

Tak

Zaimplementuj autouzupełnianie miejsc automatycznie bez tokenów sesji i wywołaj interfejs Geocoding API przy użyciu wybranej prognozy miejsca.
Interfejs Geocoding API dostarcza adresy i współrzędne geograficzne w cenie 0,005 USD na żądanie. Dodanie 4 żądań autouzupełniania miejsc – na żądanie kosztuje 0,01132 USD, więc łączny koszt 4 żądań i wywołanie Geocoding API na temat wybranej prognozy miejsca to 0,01632 USD, czyli mniej niż cena autouzupełniania na sesję 0,017 USD1.

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby ułatwić użytkownikom uzyskiwanie prognozowanych haseł o mniejszej liczbie znaków.

Nie

Korzystaj z autouzupełniania miejsc opartych na sesjach ze szczegółami miejsca.
Średnia liczba żądań, które ma zostać wysłana, zanim użytkownik wybierze przewidywaną liczbę wyświetleń z autouzupełniania miejsc przekracza koszt modelu, więc Twoja implementacja autouzupełniania miejsc powinna używać tokena sesji zarówno dla żądań autouzupełniania miejsc, jak i powiązanych z nimi żądań Szczegóły.1

Implementacja widżetów
Zarządzanie sesjami jest wbudowane w widżety JavaScript, Androida lub iOS. Obejmuje to prośby o autouzupełnianie miejsc i żądania szczegółów miejsca dotyczące wybranej prognozy. Pamiętaj, aby podać parametr fields, aby mieć pewność, że wysyłasz tylko żądania dotyczące danych podstawowych.

Automatyzacja implementacji
Użyj tokena sesji w żądaniach autouzupełniania miejsc. Podczas wysyłania prośby o szczegóły miejsca związane z wybraną prognozą podaj te parametry:

  1. Identyfikator miejsca podany w odpowiedzi miejsca autouzupełniania.
  2. Token sesji używany w żądaniu autouzupełniania miejsc
  3. Parametr fields określający pola Dane podstawowe, takie jak adres i geometria.

Rozważ opóźnianie żądań autouzupełniania miejsc
Możesz stosować strategie takie jak opóźnianie żądania autouzupełniania miejsc, dopóki użytkownik nie wpisze pierwszych 3–4 znaków. Dzięki temu liczba żądań w aplikacji będzie mniejsza. Jeśli na przykład wyślesz żądanie autouzupełniania miejsc dla każdego znaku po wpisaniu trzeciego znaku, to gdy użytkownik wpisze 7 znaków, a później wybierze podpowiedź, dla której wyślesz jedno żądanie interfejsu Geocoding API, łączny koszt wyniesie 0,01632 zł (4 * 0,00283 zł do autouzupełniania na żądanie + 0,005 zł do geokodowania).1

Jeśli opóźnione żądania mogą sprawić, że Twoja średnia prośba o wykorzystanie automatyzacji będzie niższa niż 4, postępuj zgodnie ze wskazówkami dotyczącymi implementacji automatycznego uzupełniania miejsca za pomocą interfejsu Geocoding API. Pamiętaj, że opóźnienia żądania mogą być postrzegane przez użytkowników jako takich, którzy mogą spodziewać się podpowiedzi po każdym nowym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby ułatwić użytkownikom uzyskiwanie prognozowanych zapytań zawierających mniej znaków.


  1. Wymienione koszty są podane w dolarach amerykańskich. Pełne informacje o cenach znajdziesz na stronie Rozliczenia w Google Maps Platform.

Sprawdzone metody zwiększania skuteczności

Te wskazówki opisują sposoby optymalizacji skuteczności autouzupełniania miejsc:

  • Dodaj ograniczenia językowe, promowanie lokalizacji i preferencja języka (w przypadku implementacji automatycznych) do implementacji autouzupełniania miejsc. W przypadku widżetów nie trzeba określać języka, ponieważ język jest wybierany w przeglądarce lub na urządzeniu mobilnym użytkownika.
  • Jeśli wraz z mapą pojawia się autouzupełnianie miejsca, możesz wskazać lokalizację na podstawie widocznego obszaru mapy.
  • Jeśli użytkownik nie wybierze jednej z podpowiedzi autouzupełniania (zwykle nie jest to pożądany adres wyniku), możesz spróbować jeszcze raz użyć oryginalnych danych wejściowych użytkownika, aby uzyskać trafniejsze wyniki:
    • Jeśli oczekujesz, że użytkownik poda tylko informacje adresowe, użyj wywołania pierwotnego interfejsu Geocoding API jeszcze raz.
    • Jeśli spodziewasz się, że użytkownik wpisze zapytanie dotyczące określonego miejsca według nazwy lub adresu, użyj żądania Znajdź miejsce. Jeśli wyniki są oczekiwane tylko w określonym regionie, użyj promowania lokalizacji.
    Inne sytuacje, w których najlepiej jest wrócić do interfejsu Geocoding API:
    • Użytkownicy podający adresy podrzędne w krajach innych niż Australia, Nowa Zelandia lub Kanada Na przykład amerykański adres „123 Bowdoin St #456, Boston MA, Stany Zjednoczone” nie jest obsługiwany przez autouzupełnianie. (Autouzupełnianie obsługuje adresy podrzędne tylko w Australii, Nowej Zelandii i Kanadzie). Obsługiwane formaty adresów w tych 3 krajach to „9/321 Pitt Street, Sydney, New South Wales, Australia” lub „14/19 Langana Avenue, Browns Bay, Auckland, New Zealand” lub „145-112 Renfrew Dr, Markham, Ontario, Canada”.
    • Użytkownicy wpisują adresy z prefiksami segmentów drogi, np. „23-30 29th St, Queens” w Nowym Jorku, lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai w Hawai'i.

Rozwiązywanie problemów

Choć może występować wiele różnych błędów, większość błędów może być zwykle spowodowanych przez błędy konfiguracji (np. nieprawidłowy klucz interfejsu API lub nieprawidłowo skonfigurowany klucz interfejsu API) lub błędy limitu (aplikacja przekroczyła limit). Zobacz Limity użytkowania, aby dowiedzieć się więcej o limitach.

Błędy, które pojawiają się przy użyciu elementów autouzupełniania, są zwracane w wywołaniu zwrotnym onActivityResult(). Zadzwoń pod numer Autocomplete.getStatus(), aby zobaczyć komunikat o stanie wyniku.