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 Places SDK dla Androida zwraca prognozy w odpowiedzi na zapytania użytkowników. Gdy użytkownik wprowadza typ, 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 kilka sposobów:

Dodawanie widżetu autouzupełniania

Widżet autouzupełniania to okno wyszukiwania z wbudowaną funkcją autouzupełniania. Gdy użytkownik wpisuje wyszukiwane hasło, widżet wyświetla listę przewidywanych miejsc do wyboru. Gdy użytkownik dokona wyboru, zostanie zwrócony obiekt Place, którego aplikacja może następnie 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 autouzupełniania

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 działania

Aby dodać do działania 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 zachować spójny wygląd, zagnieźdź fragment w innym elemencie układu, np. w elemencie CardView.
  • Jeśli używasz fragmentu autouzupełniania i chcesz zastąpić ustawienie 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 w 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 (np. do aktywowania autouzupełniania na podstawie ikony zamiast pola wyszukiwania), aplikacja może uruchomić autouzupełnianie na podstawie intencji.

Aby uruchomić widżet autouzupełniania przy użyciu intencji, wykonaj te czynności:

  1. Aby utworzyć intencję, przekazujemy odpowiedni tryb Autocomplete za pomocą Autocomplete.IntentBuilder. Intencja musi wywoływać metodę startActivityForResult, przesyłając kod żądania identyfikujący intencję.
  2. Zastąp wywołanie zwrotne onActivityResult, aby otrzymać wybrane miejsce.

Tworzenie intencji autouzupełniania

Poniższy przykład pokazuje użycie Autocomplete.IntentBuilder do utworzenia zamiaru uruchomienia widżetu 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)

      

Gdy chcesz uruchomić widżet autouzupełniania, możesz wybrać tryb nakładki lub wyświetlania na pełnym ekranie. Poniższe zrzuty ekranu pokazują każdy tryb wyświetlania:

W trybie nakładki wyświetlany jest widżet autouzupełniania nałożony na interfejs użytkownika wywołującego.
Ilustracja 1. Autouzupełnianie widżetu w trybie nakładania
Widżet autouzupełniania 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, gdy użytkownik wybierze miejsce, Twoja aplikacja powinna zastąpić onActivityResult() aktywności, sprawdzając kod żądania przekazany dla intencji, jak pokazano w przykładzie poniżej.

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 dostarczonego przez widżet autouzupełniania możesz utworzyć własny interfejs wyszukiwania. Aby to zrobić, aplikacja musi automatycznie generować prognozy miejsc. Twoja aplikacja może uzyskać z interfejsu autouzupełniania API listę przewidywanych nazw miejsc lub adresów, wywołując interfejs PlacesClient.findAutocompletePredictions() i przekazując obiekt FindAutocompletePredictionsRequest z tymi parametrami:

  • Wymagany: ciąg znaków query zawierający tekst wpisany przez użytkownika.
  • Zalecane: AutocompleteSessionToken, który grupuje fazy zapytania i wyboru użytkownika w osobne sesje do celów rozliczeniowych. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierze miejsce.
  • Zalecane: obiekt RectangularBounds, który określa granice szerokości i długości geograficznej, by ograniczyć wyniki do określonego regionu.
  • Opcjonalnie: co najmniej 1-literowy kod kraju (ISO 3166-1 alfa-2) wskazujący kraj, do którego wyniki mają zostać ograniczone.
  • Opcjonalny: 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 tej prośby, by jednoznacznie określić wyniki, których określona lokalizacja może być nieokreślona.
    • TypeFilter.ADDRESS – zwraca tylko wyniki autouzupełniania z dokładnym adresem. Użyj tego typu, jeśli 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 pasujące 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ę punktu początkowego żądania. Gdy wywołujesz setOrigin(), usługa zwraca odległość w metrach (distanceMeters) od określonego punktu początkowego na potrzeby każdej prognozy autouzupełniania w odpowiedzi.

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 zwróci wartość FindAutocompletePredictionsResponse w obiekcie Task. FindAutocompletePredictionsResponse zawiera listę obiektów AutocompletePrediction reprezentujących przewidywane miejsca. Lista może być pusta, jeśli nie istnieje żadne znane miejsce odpowiadające zapytaniu i kryteriom filtra.

Dla każdego prognozowanego miejsca można wywołać te metody, aby uzyskać szczegółowe informacje o miejscu:

  • getFullText(CharacterStyle) zwraca pełny tekst opisu miejsca. To połączenie tekstu głównego i dodatkowego. Przykład: „Eiffel Tower, Avenue Anatole France, Paryż, Francja”. Dodatkowo ta metoda umożliwia wyróżnianie sekcji opisu pasującego do wyszukiwanego stylu za pomocą CharacterStyle. Parametr CharacterStyle jest opcjonalny. Jeśli nie potrzebujesz wyróżniania tekstu, ustaw wartość null.
  • getPrimaryText(CharacterStyle) zwraca główny tekst opisujący miejsce. Jest to zwykle nazwa miejsca. Przykłady: „Eiffel Tower” i „123 Pitt Street”.
  • getSecondaryText(CharacterStyle) zwraca tekst podmiotu zależnego z opisu miejsca. 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 identyfikator tekstowy, który jednoznacznie identyfikuje miejsce i służy do późniejszego pobrania obiektu Place. Więcej informacji o identyfikatorach miejsc w pakiecie Miejsc dla Androida znajdziesz 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 między metrami a miejscem podanym w żądaniu.

Tokeny sesji

Tokeny sesji grupują fazy zapytania i wyboru w autouzupełnianiu wyszukiwań użytkowników w osobne sesje do celów rozliczeniowych. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierze miejsce. Każda sesja może zawierać wiele zapytań z 1 wybranym miejscem. Po zakończeniu sesji token jest nieważny – aplikacja musi wygenerować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji dla wszystkich sesji autouzupełniania automatyzacji (gdy umieścisz fragment lub uruchomisz autouzupełnianie za pomocą intencji, interfejs API zajmie się tym automatycznie).

Pakiet SDK Miejsc na Androida wskazuje każdą sesję za pomocą AutocompleteSessionToken. Po rozpoczęciu każdej nowej sesji aplikacja powinna przekazać nowy token sesji, a potem ten sam token wraz z identyfikatorem miejsca w kolejnym wywołaniu fetchPlace(). Dzięki temu uzyskasz szczegółowe informacje o miejscu wybranym przez użytkownika.

Więcej informacji o tokenach sesji

Ograniczanie wyników autouzupełniania

Można ograniczyć wyniki autouzupełniania do określonego regionu geograficznego lub filtrować je według jednego lub kilku typów miejsc albo do maksymalnie 5 krajów. Te ograniczenia możesz zastosować do działania autouzupełniania oraz interfejsów API autouzupełniania AutocompleteSupportFragment.

Aby ograniczyć wyniki, wykonaj te czynności:

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

Wyniki w konkretnym regionie

Aby odchylenie wyników autouzupełniania było określane dla określonego regionu geograficznego, wywołaj metodę setLocationBias(), przekazując RectangularBounds. Ten przykładowy kod pokazuje, że wywołanie setLocationBias() powoduje wystąpienie fragmentu z autouzupełnianiem sugestii 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)
        )
    )

      

Ogranicz wyniki do określonego regionu

Aby ograniczyć wyniki autouzupełniania do określonego regionu geograficznego, wywołaj setLocationRestriction() i przekaż RectangularBounds. Poniższy przykładowy kod pokazuje, jak wywołać metodę setLocationRestriction() w instancji fragmentu, aby kierować sugestie autouzupełniania do 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 jest stosowane tylko do całych tras. Wyniki syntetyczne zlokalizowane poza prostokątnymi granicami mogą być zwracane na podstawie trasy nakładającej się z ograniczeniami lokalizacji.

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

Możesz ograniczyć wyniki żą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ślono inaczej, zwracane są wszystkie typy.

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

Aby określić filtr typu lub typu kolekcji:

  • Wywołaj setTypesFilter() i określ do 5 wartości typu z tabel 1 i tabeli 2 wyświetlanych w sekcji Typy miejsc. Wartości typów są określane stałymi w polach PlaceTypes.

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

    W żądaniu można podać tylko jeden typ z tabeli 3. Jeśli określisz wartość w tabeli 3, nie możesz określić wartości z tabeli 1 lub tabeli 2. Jeśli to zrobisz, wystąpi błąd.

Ten przykładowy kod wywołuje metodę setTypesFilter() na elemencie 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ład kodu pokazuje, jak działa wywołanie setTypesFilter() na urządzeniu AutocompleteSupportFragment, aby ustawić filtr zwracający tylko wyniki z dokładnym adresem poprzez określenie zbioru typów.

Java


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

      

Kotlin


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

      

Poniższy przykładowy kod pokazuje, jak wywołać tag setTypesFilter() na urządzeniu IntentBuilder, aby ustawić filtr zwracający tylko wyniki z dokładnym adresem poprzez określenie zbioru 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)

      

Filtruj wyniki według kraju

Aby odfiltrować wyniki autouzupełniania do maksymalnie 5 krajów, zadzwoń pod numer 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, jak wywołać setCountries() na AutocompleteSupportFragment, aby ustawić filtr, który zwraca tylko wyniki z określonych krajów.

Java


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

      

Kotlin


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

      

Limity wykorzystania

Wykorzystanie interfejsu Places API, w tym Places SDK na Androida, nie jest już ograniczone do maksymalnej liczby żądań dziennie. Nadal obowiązują jednak te limity wykorzystania:

  • Limit szybkości wynosi 100 żądań na sekundę. Jest to suma żądań po stronie klienta i po stronie serwera dla wszystkich aplikacji, które używają danych logowania tego samego projektu.

Wyświetlanie atrybucji w aplikacji

  • Jeśli Twoja aplikacja korzysta z usługi autouzupełniania w sposób zautomatyzowany, Twój interfejs użytkownika musi wyświetlać atrybucję „Technologia Google” lub być widoczny na mapie marki Google.
  • Jeśli aplikacja korzysta z widżetu autouzupełniania, nie są wymagane żadne dodatkowe działania (jest ona wyświetlana domyślnie).
  • Jeśli po uzyskaniu identyfikatora według miejsca pobierasz i wyświetlasz dodatkowe informacje o miejscu, musisz też podać atrybucję firm zewnętrznych.

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

Optymalizacja autouzupełniania miejsc

W tej sekcji znajdziesz sprawdzone metody, które pomogą Ci w pełni wykorzystać możliwości usługi autouzupełniania miejsc.

Oto kilka ogólnych wskazówek:

  • Najszybszym sposobem na utworzenie działającego interfejsu użytkownika jest użycie widżetu autouzupełniania w interfejsie Maps JavaScript, widżetu autouzupełniania w pakiecie SDK do Androida lub sposobu kontroli interfejsu użytkownika autouzupełniania w pakiecie SDK dla iOS.
  • Naucz się najważniejszych pól danych autouzupełniania miejsc od samego początku.
  • Pola promowania ze względu na lokalizację i ograniczenia dotyczące lokalizacji są opcjonalne, ale mogą mieć duży wpływ na skuteczność autouzupełniania.
  • Użyj obsługi błędów, aby aplikacja działała płynnie w przypadku błędu interfejsu API.
  • Dopilnuj, aby aplikacja obsługiwała, gdy nie jest wybrana żadna opcja, i aby użytkownicy mogli go kontynuować.

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 szczegółach szczegółów miejsca i widżetów autouzupełniania miejsc, aby zwracać tylko wymagane pola danych o miejscach.

Zaawansowana optymalizacja kosztów

Rozważ użycie implementacji autouzupełniania miejsc, aby uzyskać dostęp do cennika według żądania i poprosić o wyniki interfejsu API dotyczące geokodowania dotyczące wybranego miejsca zamiast szczegółowych informacji o miejscu. Ceny na żądanie w połączeniu z interfejsem API kodowania geograficznego są bardziej opłacalne niż model na sesję (na podstawie sesji), 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, interfejs Geocoding API dostarcza te informacje w przypadku mniejszej liczby wywołań miejsca.
  • Jeśli użytkownicy wybiorą prognozę autouzupełniania w średnio 4 żądaniach autouzupełniania prognozowanych lub niższych, ustalanie cen na żądanie może być bardziej opłacalne niż model cenowy sesji.
Aby uzyskać pomoc w implementacji autouzupełniania miejsc, należy wybrać kartę odpowiadającą odpowiedzi na poniższe pytanie.

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

Tak, chcę więcej informacji

Korzystaj z autouzupełniania miejsc na podstawie sesji z informacjami o miejscu.
Twoja aplikacja wymaga szczegółowych informacji o miejscu, takich jak nazwa miejsca, status firmy czy godziny otwarcia, dlatego implementacja autouzupełniania powinna korzystać z tokena sesji (automatycznego albo wbudowanego w widżety JavaScript, Androida lub iOS) za łączny koszt wynoszący 0,017 USD na sesję plus odpowiednie kody danych miejsca w zależności od żądanych pól danych o miejscu.

Implementacja widżetów
Zarządzanie sesją jest automatycznie wbudowane w widżety
JavaScript, Android lub iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądania miejsc dotyczące wybranych prognoz. Określ parametr fields, aby mieć pewność, że wysyłasz tylko wymagane pola danych o miejscach.

Wdrażanie automatyzacji
W przypadku żądań autouzupełniania w miejscu użyj tokena sesji. Żądając szczegółów miejsca dotyczących wybranej prognozy, podaj te parametry:

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

Nie, wymaga tylko adresu i lokalizacji

W zależności od wydajności użycia funkcji autouzupełniania w miejscu docelowym aplikacja Geocoding API może być bardziej opłacalną opcją niż szczegóły miejsca. Wydajność autouzupełniania każdej aplikacji różni się w zależności od tego, co użytkownicy wpisują, gdzie jest używana i czy zastosowano sprawdzone metody optymalizacji skuteczności.

Aby odpowiedzieć na to pytanie, przeanalizuj średnią liczbę znaków wpisywanych przez użytkownika przed wybraniem podpowiedzi autouzupełniania w aplikacji.

Czy użytkownicy częściej wybierają prognozę autouzupełniania miejsc w maksymalnie 4 żądaniach?

Tak

Zaimplementuj automatyczne uzupełnianie miejsc bez tokenów sesji i wywołuj interfejs Geocoding API w prognozie dotyczącej wybranego miejsca.
Interfejs Geocode API udostępnia adresy i szerokość i szerokość geograficzną w cenie 0,005 USD za żądanie. Wystąpienie 4 żądań autouzupełniania miejsc – na żądanie kosztuje 0,01132 USD, więc łączny koszt 4 żądań plus wywołanie Geocoding API dotyczące prognozy wybranego miejsca wyniesie 0,01632 USD, czyli mniej niż cena autouzupełniania na sesję wynoszącą 0,017 USD.1

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby ułatwić użytkownikom wyświetlanie podpowiedzi, których jeszcze nie używają.

Nie

Korzystaj z autouzupełniania miejsc na podstawie sesji z informacjami o miejscu.
Ponieważ średnia liczba żądań, które oczekujesz od użytkownika, zanim użytkownik wybierze prognozę prognozy dotyczącej autouzupełniania miejsc, przekracza koszt ceny na sesję, w Twojej implementacji autouzupełniania miejsc należy użyć tokena sesji zarówno w przypadku żądań autouzupełniania miejsc, jak i powiązanych żądań informacji o miejscu.Ten koszt wynosi 0,017 USD na sesję.1

Implementacja widżetów
Zarządzanie sesją jest automatycznie wbudowane w widżety JavaScript, Android lub iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądania miejsc dotyczące wybranych prognoz. Określ parametr fields, aby mieć pewność, że wysyłasz tylko żądania dotyczące danych podstawowych.

Wdrażanie automatyzacji
W przypadku żądań autouzupełniania w miejscu użyj tokena sesji. Żądając szczegółów miejsca dotyczących wybranej prognozy, podaj te parametry:

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

Rozważ opóźnienie żądań autouzupełniania miejsc
Możesz stosować strategie, takie jak opóźnienie żądania autouzupełniania miejsc, dopóki użytkownik nie wpisze pierwszych 3 lub 4 znaków, aby Twoja aplikacja wysyłała mniej żądań. Na przykład wysyłanie żądań autouzupełniania miejsc dla każdego znaku po wpisaniu trzeciego znaku oznacza, że jeśli użytkownik wpisze 7 znaków, a potem wybierze prognozę, w przypadku której wyślesz 1 żądanie interfejsu Geocoding API, całkowity koszt wyniesie 0,01632 PLN (4 * 0,00283 autouzupełniania na żądanie + 0,005 PLN).

Jeśli opóźnione żądania mogą spowodować żądanie średniej automatyzacji poniżej 4, możesz postępować zgodnie ze wskazówkami dotyczącymi implementacji autouzupełniania miejsc z użyciem interfejsu Geocode API. Opóźnienie żądań może być odbierane przez użytkowników, którzy mogą oczekiwać podpowiedzi po każdym nowym naciśnięciu klawisza.

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby ułatwić użytkownikom wyświetlanie podpowiedzi, których szuka (mniej znaków).


  1. Wymienione tutaj koszty są w dolarach amerykańskich. Pełne ceny znajdziesz na stronie Płatności w Google Maps Platform.

Sprawdzone metody dotyczące skuteczności

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

  • Dodaj ograniczenia językowe, promowania lokalizacji i preferencji języka w implementacji autouzupełniania miejsc. W przypadku widżetów wybór języka jest niepotrzebny, ponieważ to one wybierają przeglądarkę w przeglądarce lub na urządzeniu mobilnym użytkownika.
  • Jeśli umiejscowieniu autouzupełniania miejsca towarzyszy mapa, możesz odchylenia lokalizacji na podstawie widocznego obszaru mapy.
  • Jeśli użytkownik nie wybierze jednego z podpowiedzi autouzupełniania, zwykle dlatego, że żadna z nich nie jest pożądanym adresem wyniku. Aby uzyskać trafniejsze wyniki, możesz ponownie użyć danych wejściowych użytkownika:
    • Jeśli oczekujesz, że użytkownik wpisze tylko informacje adresowe, użyj ponownie danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
    • Jeśli spodziewasz się, że użytkownik wpisze zapytania dotyczące określonego miejsca według nazwy lub adresu, użyj opcji Znajdź miejsce. Jeśli wyniki są oczekiwane tylko w określonym regionie, skorzystaj z funkcji promowania lokalizacji.
    Inne scenariusze, w których najlepiej jest wrócić do interfejsu Geocoding API, to:
    • Użytkownicy wpisują adresy podrzędne w krajach, w których funkcja autouzupełniania adresów miejsc jest niekompletna, np. w Czechach, Estonii i na Litwie. Na przykład czeski adres „Stroupežnického 3191/17, Praha” generuje częściową prognozę w autouzupełnianiu miejsca.
    • Użytkownik wpisuje adres z prefiksem segmentu drogi, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawai'i.

Rozwiązywanie problemów

Błędy mogą występować w różnym stopniu, ale większość z nich prawdopodobnie wynika z błędów konfiguracji (np. użyto nieprawidłowego klucza interfejsu API, nieprawidłowo ustawiono klucz interfejsu API) lub błędów limitów (aplikacja przekroczyła limit). Więcej informacji o limitach znajdziesz w artykule Limity wykorzystania.

Błędy występujące w przypadku użycia elementów autouzupełniania są zwracane w wywołaniu zwrotnym onActivityResult(). Wywołaj Autocomplete.getStatus(), aby uzyskać komunikat o stanie wyniku.