Autouzupełnianie miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Usługa autouzupełniania w pakiecie SDK Miejsc na Androida zwraca prognozy w odpowiedzi na zapytania użytkowników. Gdy użytkownik korzysta z funkcji autouzupełniania, wyświetla ona sugestie miejsc takich jak firmy, adresy, kody Plus Code 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 wprowadza wyszukiwane hasła, widżet przedstawia listę przewidywanych miejsc do wyboru. Gdy użytkownik dokona wyboru, zostanie zwrócona instancja Place, która może zostać użyta przez aplikację do uzyskania szczegółowych informacji o wybranym miejscu.

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

Opcja 1. Umieść funkcję AutocompleteSupportFragment

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 aktywności element AutocompleteSupportFragment, dodaj nowy fragment do układu XML. Na przykład:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />
  • Domyślnie fragment nie ma obramowania ani tła. Aby zapewnić spójny wygląd, zagnieźdź fragment w innym elemencie układu, takim jak CardView.
  • Jeśli używasz fragmentu autouzupełniania i musisz zastąpić tag 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 wybory 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 aplikacja ma korzystać z innego sposobu nawigacji (na przykład w celu aktywowania autouzupełniania przy użyciu ikony zamiast pola wyszukiwania), aplikacja może uruchomić autouzupełnianie z wykorzystaniem intencji.

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

  1. Użyj metody Autocomplete.IntentBuilder, aby utworzyć intencję, przekazując odpowiedni tryb Autocomplete.
  2. Zdefiniuj program uruchamiający wyniki aktywności registerForActivityResult, który może służyć do uruchamiania intencji i obsługiwania prognozowanego przez użytkownika miejsca w wyniku.

Tworzenie intencji autouzupełniania

W przykładzie poniżej użyto Autocomplete.IntentBuilder do utworzenia intencji uruchomienia autouzupełniania jako intencji:

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

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

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

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

Jeśli chcesz uruchomić widżet autouzupełniania, możesz wybrać tryb nakładki lub pełnoekranowego ekranu. Te zrzuty ekranu pokazują każdy tryb wyświetlania:

W trybie nakładki widżet autouzupełniania nakłada się na interfejs do rozmów.
Ilustracja 1. Autouzupełnianie widżetu w trybie nakładki
Widżet autouzupełniania wyświetla cały ekran w trybie pełnoekranowym.
Ilustracja 2. Autouzupełnianie widżetu w trybie FULLSCREEN

Zarejestruj wywołanie zwrotne dla wyniku intencji

Aby otrzymać powiadomienie, gdy użytkownik wybierze miejsce, określ program uruchamiający registerForActivityResult(), który uruchamia aktywność i obsługuje wynik w poniższym przykładzie. Jeśli użytkownik wybrał prognozę, zostanie ona wyświetlona w intencji uwzględnionej w obiekcie wyniku. Intencja została utworzona przez Autocomplete.IntentBuilder, więc metoda Autocomplete.getPlaceFromIntent() może z niej wyodrębnić obiekt Place.

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);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

Kotlin


private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

Automatyczne prognozowanie miejsc

Zamiast interfejsu udostępnianego przez widżet autouzupełniania możesz utworzyć własny interfejs wyszukiwarki. Aby było to możliwe, aplikacja musi automatycznie generować prognozy miejsc. Aplikacja może uzyskać listę przewidywanych nazw miejsc lub adresów z interfejsu autouzupełniania API, wywołując interfejs PlacesClient.findAutocompletePredictions(), 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 ramach określonej sesji do celów rozliczeniowych. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, i kończy się, gdy użytkownik wybierze miejsce.
  • Zalecane: obiekt RectangularBounds, który wyznacza 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, do którego należy ograniczyć wyniki.

  • Opcjonalne: TypeFilter, którego możesz użyć, by 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, jeśli określona lokalizacja może być nieokreślona.
    • TypeFilter.ADDRESS – zwraca tylko wyniki autouzupełniania zawierające dokładny adres. Używaj tego typu, jeśli wiesz, że użytkownik szuka pełnego 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.

  • Opcjonalne: LatLng określające lokalizację punktu początkowego żądania. Gdy wywołujesz metodę setOrigin(), usługa zwraca dystans w metrach (distanceMeters) od wybranego źródła w przypadku każdej prognozy autouzupełniania w odpowiedzi.

Informacje o typach miejsc znajdziesz w przewodniku po typach miejsc.

Poniższy przykład zawiera 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(PlaceTypes.ADDRESS))
            .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(PlaceTypes.ADDRESS))
            .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. Lista może być pusta, jeśli nie ma znanego miejsca odpowiadającego zapytaniu i filtrom.

W przypadku każdego prognozowanego miejsca możesz wywołać te metody, by pobrać informacje o miejscu:

  • getFullText(CharacterStyle) zwraca pełny opis opisu miejsca. Jest to kombinacja tekstu głównego i dodatkowego. Przykład: „wieża Eiffla, aleja Anatole'a we Francji, Paryż, Francja”. Dodatkowo ta metoda pozwala wyróżnić sekcje tekstu, które pasują do wyszukiwania za pomocą wybranego stylu, za pomocą CharacterStyle. Parametr CharacterStyle jest opcjonalny. Jeśli nie potrzebujesz podświetlenia, ustaw wartość null.
  • getPrimaryText(CharacterStyle) zwraca główny tekst opisujący miejsce. Zwykle jest to nazwa miejsca. Przykłady: „wieża Eiffla” i „Ulica 123 ”.
  • getSecondaryText(CharacterStyle) zwraca tekst podmiotu zależnego opisujący opis 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 prognozowanego. Identyfikator miejsca to identyfikator tekstowy, który jednoznacznie identyfikuje miejsce. Możesz go później użyć do odzyskania obiektu Place. Więcej informacji o identyfikatorach miejsc w pakiecie SDK Miejsc na Androida znajdziesz w szczegółach 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 linii prostej między danym miejscem a źródłem określonym w żądaniu.

Tokeny sesji

Tokeny sesji grupują fazę zapytania i wyboru użytkownika w autouzupełnianiu wyszukiwania do konkretnej sesji do celów rozliczeniowych. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, i kończy się, gdy użytkownik wybierze miejsce. Każda sesja może mieć wiele zapytań, po których następuje jeden wybór miejsca. Po zakończeniu sesji token jest już nieważny. Aplikacja musi wygenerować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji w przypadku wszystkich sesji autouzupełniania zautomatyzowanego (gdy umieścisz fragment lub uruchomisz autouzupełnianie z intencją, interfejs API zajmie się tą sprawą 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 razem z identyfikatorem miejsca w kolejnym wywołaniu funkcji fetchPlace(), aby pobrać Szczegóły miejsca wybranego przez użytkownika.

Więcej informacji o tokenach sesji

Ogranicz wyniki autouzupełniania

Możesz ograniczyć wyniki autouzupełniania do konkretnego regionu geograficznego lub przefiltrować wyniki według jednego lub kilku typów miejsc, a nawet do pięciu krajów. Te ograniczenia możesz zastosować do aktywności autouzupełniania, AutocompleteSupportFragment i interfejsów API autouzupełniania.

Aby ograniczyć wyniki, wykonaj te czynności:

  • Aby preferować wyniki w zdefiniowanym regionie, wywołaj metodę setLocationBias() (niektóre wyniki spoza określonego regionu mogą nadal być zwracane).
  • Aby wyświetlić wyniki tylko z wybranego regionu, wywołaj metodę setLocationRestriction() (zostaną zwrócone tylko wyniki z wybranego regionu).
  • Aby wyświetlić tylko wyniki zgodne z konkretnym typem miejsca, wywołaj funkcję setTypesFilter() (np. określenie TypeFilter.ADDRESS spowoduje zwrócenie tylko wyników z dokładnym adresem).
  • Aby wyświetlić tylko wyniki w maksymalnie 5 określonych krajach, wywołaj metodę setCountries(). Kraje należy przekazywać jako dwuznakowy kod kraju zgodny ze standardem ISO 3166-1 alfa-2.

Wyniki odchylenia do określonego regionu

Aby odchylenie wyników autouzupełniania w określonym regionie geograficznym było możliwe, wywołaj metodę setLocationBias(), przekazując RectangularBounds. Ten przykładowy kod pokazuje wywoływanie setLocationBias() w instancji fragmentu, aby stronniczość sugestii autouzupełniania zwiększała się do 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 konkretnego regionu

Aby ograniczyć wyniki autouzupełniania do określonego regionu geograficznego, wywołaj metodę setLocationRestriction(), przekazując RectangularBounds. Ten przykładowy kod pokazuje wywoływanie setLocationRestriction() w instancji fragmentu, aby stronnicze sugerował autouzupełnienie dotyczące 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, które znajdują się poza prostokątnymi granicami, mogą zostać zwrócone na podstawie trasy, która pokrywa się z ograniczeniem lokalizacji.

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

Możesz ograniczyć wyniki żądania autouzupełniania, aby zwracały tylko określony typ miejsca. Określ filtr za pomocą typów miejsc lub kolekcji typów wymienionych w tabelach 1, 2 i 3 w sekcji Typy miejsc. Jeśli nie określono żadnej właściwości, zwracane są wszystkie typy.

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

Aby określić filtr typu lub zbioru:

  • 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ą definiowane przez stałe w obiekcie PlaceTypes.

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

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

Ten przykładowy kod wywołuje metodę setTypesFilter() na obiekcie AutocompleteSupportFragment i określa wartości wielu typów.

Java


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

Kotlin


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

Poniższy przykład kodu pokazuje wywołanie setTypesFilter() na AutocompleteSupportFragment, aby ustawić filtr zwracający tylko wyniki z dokładnym adresem, określając kolekcję typów.

Java


    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

Kotlin


    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

Poniższy przykład kodu pokazuje wywołanie setTypesFilter() w IntentBuilder, aby ustawić filtr zwracający tylko wyniki z dokładnym adresem, określając kolekcję typów.

Java


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

Kotlin


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

Filtruj wyniki według kraju

Aby filtrować wyniki autouzupełniania maksymalnie do 5 krajów, wywołaj setCountries() i ustaw 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.

Ten przykładowy kod pokazuje wywoływanie setCountries() w 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

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

  • Limit liczby żądań to 100 na sekundę. Jest to suma żądań po stronie klienta i po stronie serwera 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, w interfejsie użytkownika musi się wyświetlać informacja „Technologia Google” lub mapa Google.
  • Jeśli aplikacja korzysta z widżetu autouzupełniania, nie są wymagane żadne dodatkowe działania (domyślnie wyświetlana jest wymagana atrybucja).
  • Jeśli pobierasz i wyświetlasz dodatkowe informacje o miejscu po uzyskaniu miejsca według identyfikatora, musisz wyświetlać też atrybucje zewnętrzne.

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

Optymalizacja autouzupełniania miejsc

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

Oto kilka ogólnych wskazówek:

Sprawdzone metody optymalizacji kosztów

Podstawowa optymalizacja kosztów

Aby zoptymalizować koszty korzystania z usługi autouzupełniania miejsc, użyj masek pól w szczegółach miejsca i autouzupełnianiu miejsc, aby zwracać tylko potrzebne pola danych o miejscach.

Zaawansowana optymalizacja kosztów

Rozważ zautomatyzowaną implementację autouzupełniania miejsc, aby uzyskać dostęp do cen według żądania i poprosić o wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast szczegółowych informacji o miejscu. Model cenowy żądania na żądanie w połączeniu z interfejsem Geocode API jest bardziej ekonomiczny niż model cenowy 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 przez użytkownika miejsca, interfejs Geocoding API dostarcza tych informacji w ramach mniejszej liczby wywołań szczegółów miejsca.
  • Jeśli użytkownik wybierze prognozę autouzupełniania w średnio 4 żądaniach autouzupełniania w prognozie lub mniejszej, model cenowy żądania na żądanie może być bardziej opłacalny niż model cenowy sesji.
Aby uzyskać pomoc dotyczącą wyboru autouzupełniania miejsc, które odpowiada Twoim potrzebom, kliknij kartę odpowiadającą Twojej odpowiedzi na poniższe pytanie.

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

Tak, potrzebuję więcej informacji

Korzystaj z autouzupełniania miejsc na podstawie sesji z informacjami o miejscu.
Twoja aplikacja wymaga informacji o miejscu, takich jak nazwa miejsca, stan firmy czy godziny otwarcia, dlatego w ramach autouzupełniania miejsca musisz użyć tokena sesji (zautomatyzowanego lub wbudowanego widżetu JavaScript, Androida lub iOS) o łącznym koszcie 0,017 za sesję i obowiązujących kodów SKU danych miejsca w zależności od tego, o które dane prosisz.

Implementacja widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Androida i iOS. Obejmuje to żądania autouzupełniania miejsc i prośby o dane miejsca wybrane dla prognozy. Pamiętaj o określeniu parametru fields, by mieć pewność, że wysyłasz tylko te pola danych miejsca, których potrzebujesz.

Zautomatyzowana implementacja
W żądaniach autouzupełniania miejsc używaj tokena. Gdy wysyłasz prośbę o szczegóły miejsca dotyczące wybranej prognozy, uwzględnij 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, potrzebny jest tylko adres i lokalizacja

Interfejs Geocode API może być bardziej opłacalnym rozwiązaniem niż szczegółowe informacje o miejscu w aplikacji, w zależności od wydajności autouzupełniania. Efektywność autouzupełniania każdej aplikacji różni się w zależności od danych wprowadzanych przez użytkowników, miejsc, w których są one używane, i od wdrożenia sprawdzonych metod optymalizacji wydajności.

Aby uzyskać odpowiedź na poniższe pytanie, przeanalizuj, ile znaków średnio wpisuje użytkownik przed wybraniem podpowiedzi autouzupełniania w aplikacji.

Czy użytkownicy wybierają średnio 4 lub mniej pytań dotyczących autouzupełniania miejsc?

Tak

Zaimplementuj autouzupełnianie miejsc automatycznie bez tokenów sesji i wywołuj interfejs Geocode API przy prognozowaniu wybranego miejsca.
Interfejs Geocode API dostarcza adresy oraz współrzędne geograficzne za 0,005 USD za żądanie. 4 żądania autouzupełniania miejsc – na żądanie kosztują 0,01132 zł, więc łączny koszt 4 żądań plus wywołanie geocoding API dotyczące prognozy wybranego miejsca wyniesie 0,01632 zł, czyli mniej niż cena autouzupełniania na sesję na poziomie 0,017 zł.1

Rozważ zastosowanie sprawdzonych metod dotyczących skuteczności, aby pomóc użytkownikom uzyskać prognozę, której oczekiwali nawet po mniejszej liczbie znaków.

Nie

Korzystaj z autouzupełniania miejsc na podstawie sesji z informacjami o miejscu.
Średnia liczba żądań, które możesz wysłać, zanim użytkownik wybierze prognozę autouzupełniania danych o miejscach przekracza limit kosztu sesji na sesję, dlatego w swojej implementacji autouzupełniania miejsca należy użyć tokena sesji zarówno dla żądań autouzupełniania miejsc, jak i powiązanych żądań miejsca dotyczących danego miejsca, których łączny koszt wynosi 0,017 USD za sesję.1

Implementacja widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Androida i iOS. Obejmuje to żądania autouzupełniania miejsc i prośby o dane miejsca wybrane dla prognozy. Pamiętaj o określeniu parametru fields, by mieć pewność, że wysyłasz tylko żądania dotyczące danych podstawowych.

Zautomatyzowana implementacja
W żądaniach autouzupełniania miejsc używaj tokena. Gdy wysyłasz prośbę o szczegóły miejsca dotyczące wybranej prognozy, uwzględnij 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 Dane podstawowe, takie jak adres i geometria.

Rozważ opóźnienie żądań autouzupełniania danych o miejscach
Możesz stosować strategie, np. opóźniać żądanie autouzupełniania reklam, dopóki użytkownik nie wpisze pierwszych 3 lub 4 znaków, aby Twoja aplikacja wysyłała mniej żądań. Jeśli na przykład wyślesz żądanie autouzupełniania miejsca w przypadku każdego znaku po wpisanym przez niego 3 znakami, oznacza to, że jeśli użytkownik wpisze 7 znaków, a potem wybierze podpowiedź, po której wykonasz 1 żądanie geokodowania interfejsu API, łączny koszt wyniesie 0,01632 zł (4 * 0,00283 USD za żądanie + 0,005 zł geokodowania).1

Jeśli opóźnione żądania mogą spowodować zmniejszenie średniej liczby żądań automatycznych poniżej 4, możesz stosować się do wskazówek dotyczących implementowania autouzupełniania miejsc przy użyciu interfejsu Geocode API. Opóźnienia żądań mogą być postrzegane jako opóźnienie przez użytkownika, który może oczekiwać podpowiedzi przy każdym nowym naciśnięciu klawisza.

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

  1. Koszty wymienione tutaj są podane w USD. Pełne ceny znajdziesz na stronie Płatności w Google Maps Platform.

Sprawdzone metody zapewniania skuteczności

Poniższe wskazówki opisują sposoby optymalizacji skuteczności autouzupełniania miejsc:

  • Dodaj ograniczenia językowe, promowania lokalizacji i preferencji języka (w przypadku implementacji automatycznych) do implementacji autouzupełniania miejsc. Ustawienia języka nie są potrzebne w przypadku widżetów, które wybierają ustawienia języka w przeglądarce lub na urządzeniu mobilnym użytkownika.
  • Jeśli oprócz mapy otrzymujesz funkcję autouzupełniania miejsca, możesz zwiększyć dokładność tej lokalizacji dla widocznego obszaru mapy.
  • Jeśli użytkownik nie wybierze jednej z podpowiedzi autouzupełniania, zwykle ponieważ nie jest to pożądany adres wyniku wyszukiwania, możesz ponownie użyć oryginalnych danych wejściowych użytkownika, aby uzyskać trafniejsze wyniki:
    • Jeśli oczekujesz, że użytkownik wpisze tylko dane adresowe, w wywołaniu interfejsu Geocoding API użyj danych wejściowych pierwotnego użytkownika.
    • Jeśli oczekujesz, że użytkownik wpisze zapytania 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 skorzystać z interfejsu Geocode API:
    • Użytkownicy podają adresy podrzędne w krajach, w których obsługa autouzupełniania adresów w Miejscach 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.
    • Adres wpisany na koncie w prezencie 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

Choć może się zdarzyć, że występują różne błędy, większość błędów jest zwykle spowodowana błędami konfiguracji (na przykład niewłaściwym kluczem interfejsu API lub nieprawidłowo skonfigurowanym interfejsem API) lub błędami w limitach (aplikacja przekroczyła limit). Więcej informacji o limitach znajdziesz w artykule Limity wykorzystania.

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