Autouzupełnianie miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Usługa autouzupełniania w pakiecie Places SDK dla Androida powraca w odpowiedzi na zapytania użytkowników. Podczas pisania przez użytkownika parametr autouzupełnianie zwraca propozycje miejsc takich jak firmy, adresy, kody plus oraz do ciekawych miejsc.

Możesz dodać do aplikacji funkcję autouzupełniania na jeden z tych sposobów:

• Dodaj widżet autouzupełniania, aby zapisać zmiany. czasu na tworzenie rozwiązań i zapewniać użytkownikom jednolite wrażenia.
• Pozyskiwanie prognoz dotyczących miejsc za pomocą programów w celu zapewnienia spersonalizowanych wrażeń użytkowników.

Dodawanie widżetu autouzupełniania

Widżet autouzupełniania to okno wyszukiwania z wbudowanym autouzupełnianiem funkcji. Gdy użytkownik wpisze zapytanie, widżet wyświetli listę przewidywanych miejsc do wyboru. Gdy użytkownik dokona wyboru, zwrócony zostanie obiekt Place, którego Twoja aplikacja może użyć do uzyskania szczegółowych informacji o wybranym miejscu.

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

• Opcja 1. Wstaw AutocompleteSupportFragment.
• Opcja 2. Użyj intencjonalnego wywołania aktywności autouzupełniania.

Opcja 1. Umieść fragment AutocompleteSupportFragment

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

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

Dodawanie fragmentu AutocompleteSupportFragment do aktywności

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

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

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

Dodawanie detektora PlaceSelectionListener do aktywności

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

Kotlin

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

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.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")
        }
    })

      

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

      

Opcja 2. Użyj zamiaru do uruchomienia aktywności autouzupełniania

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

Uwaga: te czynności nie są konieczne, jeśli umieszczasz fragment.

Uwaga: NIE uruchamiaj bezpośrednio usługi AutcompleteActivity. Zamiast tego użyj intencji do uruchamiania Autocomplete (PlaceAutocomplete w bibliotece zgodności).

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

1. Użyj formatu Autocomplete.IntentBuilder aby utworzyć intencję, przekazując odpowiedni tryb Autocomplete.
2. Zdefiniuj funkcję wywołania wyniku aktywności registerForActivityResult, która może służyć do uruchamiania intencji i obsługi przewidywanego miejsca wybranego przez użytkownika w wyniku.

Tworzenie intencji autouzupełniania

Przykład poniżej używa Autocomplete.IntentBuilderdo utworzenia intencji uruchamiającej widżet automatycznego uzupełniania:

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)

      

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

      

Gdy zastosujesz intencję do uruchomienia widżetu autouzupełniania, możesz wybrać jedną z tych opcji w trybie nakładki lub wyświetlania pełnoekranowego. Na poniższych zrzutach ekranu widać każdy z nich trybu wyświetlania:

Rysunek 1. Widżet autouzupełniania w trybie NAKŁADKA

Rys. 2: Widżet autouzupełniania w trybie pełnoekranowym

Rejestrowanie wywołania zwrotnego po otrzymaniu wyniku intencji

Aby otrzymywać powiadomienie, gdy użytkownik wybierze miejsce, zdefiniuj registerForActivityResult() Launcher, który uruchamia aktywność i obsługuje jak w poniższym przykładzie. Jeśli użytkownik wybrał prognozę, zostanie ona dostarczona w intencji zawartej w obiekcie wyniku. Ponieważ intencja został stworzony przez Autocomplete.IntentBuilder, metoda Autocomplete.getPlaceFromIntent() może wyodrębnić z niego obiekt Place.

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")
        }
    }

      

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

      

Pobieranie prognoz dotyczących miejsc w sposób programowy

Możesz utworzyć niestandardowy interfejs wyszukiwania jako alternatywę dla interfejsu udostępnianego przez widżet autouzupełniania. Aby było to możliwe, aplikacja musi otrzymywać prognozy dotyczące miejsc automatycznie. Aplikacja może uzyskać listę przewidywanych nazw miejsc lub z interfejsu API autouzupełniania przez wywołanie PlacesClient.findAutocompletePredictions(), zaliczając FindAutocompletePredictionsRequest o następujących parametrach:

• Wymagany: ciąg query zawierający tekst wpisany przez użytkownika.
• Zalecane: A AutocompleteSessionToken, grupuje fazy wyszukiwania i wyboru użytkownika w 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 zakresy szerokości i długości geograficznej, aby ograniczać wyniki do określonego regionu.
• Opcjonalnie: co najmniej jeden 2-literowy kraj. kodów (ISO 3166-1) alfa-2), wskazując kraj lub kraje, do których mają zostać wysłane wyniki. ograniczony.

• Opcjonalnie: TypeFilter, które 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. Należy go użyć do jednoznacznego wskazywania wyników, w przypadku których lokalizacja może być nieokreślona.
  • TypeFilter.ADDRESS – zwraca tylko wyniki autouzupełniania ze znakiem dokładny adres. Użyj tego typu, jeśli wiesz, że użytkownik szuka w pełni określony adres.
  • TypeFilter.ESTABLISHMENT – zwraca tylko miejsca, które: firmy.

  • TypeFilter.REGIONS – zwraca tylko miejsca, które pasują do jednego ze następujące typy:

  • LOCALITY

  • SUBLOCALITY

  • POSTAL_CODE

  • COUNTRY

  • ADMINISTRATIVE_AREA_LEVEL_1

  • ADMINISTRATIVE_AREA_LEVEL_2

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

• Opcjonalnie: LatLng określający lokalizację, z której pochodzi żądanie. Gdy wywołasz endpoint setOrigin(), usługa zwraca w odpowiedzi odległość w metrach (distanceMeters) od określonego punktu początkowego dla każdej prognozy autouzupełniania.

Informacje o typach miejsc znajdziesz w tym przewodniku.

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

Kotlin

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

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.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}")
            }
        }

      

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

      

Interfejs API zwraca błąd FindAutocompletePredictionsResponse w Task Obiekt FindAutocompletePredictionsResponse zawiera listę obiektów AutocompletePrediction reprezentujących przewidywane miejsca. Lista może być pusta, jeśli nie ma żadnych znanych miejsc odpowiadających zapytaniu i kryteriom filtra.

W przypadku każdego przewidywanego miejsca możesz wywołać te metody, aby uzyskać szczegóły miejsca:

• getFullText(CharacterStyle) zwraca pełny tekst opisu miejsca. Jest to kombinacja tekstu głównego i dodatkowego. Przykład: „Wieża Eiffla, aleja Anatole France, Paryż, Francja”. Dodatkowo ta metoda umożliwia wyróżnienie sekcji opisu, które pasują do wyszukiwania, za pomocą wybranego stylu (CharacterStyle). Parametr CharacterStyle jest opcjonalny. Ustaw na null, jeśli nie potrzebujesz podświetlenia.
• getPrimaryText(CharacterStyle)zwraca główny tekst opisujący miejsce. Jest to zwykle nazwa miejsce. Przykłady: „Wieża Eiffla” i „123 Pitt Street”.
• getSecondaryText(CharacterStyle) zwraca tekst dodatkowy opisu miejsca. Jest to przydatne, gdy: jako przykład w drugiej linii przy wyświetlaniu podpowiedzi autouzupełniania. Przykłady: „Avenue Anatole France, Paryż, Francja” i „Sydney, Nowa Południowa Walia”.
• getPlaceId() zwraca identyfikator przewidywanego miejsca. Identyfikator miejsca jest ciągiem tekstowym niepowtarzalny identyfikator miejsca, za pomocą którego można pobrać Place możesz zobaczyć go później. Więcej informacji o identyfikatorach miejsc w pakiecie SDK Miejsc na Androida znajdziesz w sekcji Szczegóły miejsca. Ogólne informacji o identyfikatorach miejsc znajdziesz w artykule na temat identyfikatora miejsca .
• getPlaceTypes() zwraca listę typów miejsc powiązanych z tym miejscem.
• getDistanceMeters() zwraca odległość prostą w metrach między tym miejscem a pochodzenie określone w żądaniu.

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

Możesz użyć CancellationToken, aby spróbować anulować żądanie do dowolnej klasy żądań (na przykład FetchPlaceRequest). Anulowanie odbywa się według najlepszej wiedzy. Po wysłaniu prośby o anulowanie nie otrzymasz odpowiedzi. Wystawienie tokena anulowania NIE gwarantuje, że konkretne żądanie zostanie anulowane, a opłata może zostać naliczona, nawet jeśli nie jest zwracana.

Tokeny sesji

Tokeny sesji grupują fazy zapytania i wyboru użytkownika autouzupełniania w dyskretnej sesji na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy po wybraniu miejsca. Każda sesja może zawierać wiele zapytań, a po nich wybór jednego miejsca. Gdy sesja ma że token jest już nieważny; aplikacja musi wygenerować nowy token na każdą sesję. Zalecamy korzystanie z tokenów sesji do wszystkich sesji autouzupełniania (gdy umieścisz fragment lub uruchomisz autouzupełnianie przy użyciu niż intencja, interfejs API zajmie się tym automatycznie).

Pakiet SDK Miejsca na Androida używa parametru AutocompleteSessionToken do identyfikowania każdej sesji. Aplikacja powinna przekazać nowy token sesji na początku każdej nowej sesji, a potem ten sam token wraz z identyfikatorem miejsca w kolejnych wywołaniach funkcji fetchPlace(), aby pobrać szczegóły miejsca wybranego przez użytkownika.

Wskazówka: jeśli Twoja aplikacja korzysta z widżetu Autouzupełnianie, nie musisz implementować sesji, ponieważ widżet obsługuje je automatycznie w tle.

Więcej informacji o sesji tokeny.

Ograniczanie wyników autouzupełniania

Możesz ograniczyć wyniki autouzupełniania do określonego regionu geograficznego lub odfiltrować wyniki według jednego lub większej liczby typów miejsc albo do maksymalnie 5 krajów. Ty możesz stosować te ograniczenia do autouzupełniania, AutocompleteSupportFragment oraz interfejsy API automatycznego autouzupełniania.

Aby ograniczyć wyniki, wykonaj te czynności:

• Aby preferować wyniki w określonym regionie, wywołaj funkcję setLocationBias() (nadal mogą być zwracane niektóre wyniki spoza określonego regionu).
• Aby wyświetlać tylko wyniki ze wskazanego regionu, wywołaj setLocationRestriction() (zostaną wyświetlone tylko wyniki ze zdefiniowanego regionu zwrócone).
• Aby zwrócić tylko wyniki zgodne z określonym typem miejsca, wywołaj funkcję setTypesFilter() (na przykład podanie parametru TypeFilter.ADDRESS spowoduje zwrócenie tylko wyników z dokładnym adresem).
• Aby zwrócić wyniki tylko z maksymalnie 5 określonych krajów, wywołaj funkcję setCountries(). Kraje muszą być podawane jako dwuliterowe kody krajów zgodne ze standardem ISO 3166-1 alfa-2.

Uprzedzenia wyników w konkretnym regionie

Aby zawęzić wyniki autouzupełniania do konkretnego regionu geograficznego, wywołaj funkcję setLocationBias(), przekazując parametr RectangularBounds. Poniższy przykładowy kod pokazuje wywoływanie funkcji setLocationBias() we fragmencie przez skierowanie sugestii autouzupełniania do regionu Sydney w Australii.

Kotlin

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

      

Java

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

      

Ograniczanie wyników do konkretnego regionu

Aby ograniczyć wyniki autouzupełniania do określonego regionu geograficznego, wywołaj funkcję setLocationRestriction(), podając parametr RectangularBounds. Ten przykładowy kod pokazuje, jak zadzwonić pod numer setLocationRestriction() na instancji fragmentu w celu uprzedzenia swoich sugestii autouzupełniania dla regionu Sydney, Australii.

Kotlin

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

      

Java

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

      

Uwaga: to ograniczenie dotyczy tylko całych tras. Wyniki syntetyczne znajdujące się poza granicami prostokąta mogą być zwracane na podstawie trasy, która nakłada się na ograniczenie lokalizacji.

Filtrowanie wyników według typu miejsca lub typu kolekcji

Możesz ograniczyć wyniki wyszukiwania automatycznego, aby wyświetlały tylko wyniki dotyczące określonego typu 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 podasz żadnych wartości, zwrócone zostaną wszystkie typy.

Aby filtrować wyniki autouzupełniania, zadzwoń pod numer setTypesFilter(), aby ustawić filtr.

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

• Wywołaj funkcję setTypesFilter() i określ maksymalnie 5 wartości parametru type z tabeli 1 i tabeli 2, które podano w sekcji Typy miejsc. Wartości typu to: zdefiniowane przez stałe w PlaceTypes.

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

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

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

Kotlin

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

      

Java

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

      

Poniższy przykład kodu pokazuje wywołanie funkcji setTypesFilter() w obiekcie AutocompleteSupportFragment w celu ustawienia filtra, który zwraca tylko wyniki z dokładnym adresem, przez określenie zbioru typu.

Kotlin

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

Java

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

      

Ten przykładowy kod pokazuje, jak zadzwonić pod numer setTypesFilter() na IntentBuilder, aby ustawić filtr, który zwraca tylko wyniki z dokładnym adresem, określając kolekcję typów.

Kotlin

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

      

Java

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

      

Filtruj wyniki według kraju

Aby filtrować wyniki autouzupełniania do maksymalnie 5 krajów, wywołaj setCountries() aby ustawić kod kraju. Następnie przekaż filtr do fragmentu lub intencji. Kraje muszą być przekazywane jako dwuznakowy, zgodny z normą ISO 3166-1 alfa-2 kraj w kodzie.

Poniższy przykład kodu pokazuje wywołanie funkcji setCountries() w obiekcie AutocompleteSupportFragment, aby ustawić filtr zwracający tylko wyniki z określonych krajów.

Kotlin

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

      

Java

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

      

Limity wykorzystania

Korzystanie z interfejsu Places API, w tym z pakietu Places SDK na Androida, nie jest już ograniczone do maksymalnej liczby żądań dziennie (QPD). Jednak nadal obowiązują następujące limity wykorzystania:

• Limit szybkości to 6000 QPM (żądań na minutę). Jest oblicza się jako sumę żądań po stronie klienta i po stronie serwera dla wszystkich przez aplikacje korzystające z danych logowania z tego samego projektu.

Wyświetl atrybucję w swojej aplikacji

• Jeśli aplikacja korzysta z usługi autouzupełniania za pomocą kodu, interfejs musi wyświetlać informację „Technologia Google” lub być widoczny na mapie z logo Google.
• Jeśli Twoja aplikacja korzysta z widżetu autouzupełniania, nie musisz nic robić (wymagane informacje o pochodzeniu są wyświetlane domyślnie).
• Jeśli pobierzesz i wyświetlisz dodatkowe informacje o miejscu po otrzymaniu miejsce według ID, Ty musi też zawierać informacje o autorze utworu.

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

Optymalizacja autouzupełniania miejsc

W tej sekcji znajdziesz sprawdzone metody, które pomogą Ci w pełni wykorzystać Usługa autouzupełniania miejsca.

Oto kilka ogólnych wskazówek:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest wykorzystanie Maps JavaScript API – widżet autouzupełniania, Widżet autouzupełniania Miejsc Google na Androida, lub pakietu SDK Miejsc dla systemu iOS elementów sterujących w interfejsie autouzupełniania
• Na początku zaznaj się z najważniejszymi polami danych usługi Autouzupełnianie miejsc.
• Pola promowania lokalizacji i ograniczenia lokalizacji są opcjonalne, ale mogą mają istotny wpływ na działanie autouzupełniania.
• Użyj obsługi błędów, aby zapewnić płynne działanie aplikacji, jeśli interfejs API zwróci błąd.
• Upewnij się, że aplikacja działa, gdy nie ma możliwości wyboru, i daje użytkownikom możliwość wyboru aby kontynuować.

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 widżetach Szczegóły miejsca i Autouzupełnianie miejsc, aby zwracać tylko potrzebne pola z danymi o miejscach.

Zaawansowana optymalizacja kosztów

Rozważ zautomatyzowaną implementację autouzupełniania miejsc, aby uzyskać dostęp do cen na żądanie i wysyłać żądania wyników interfejsu Geocoding API dotyczących wybranego miejsca zamiast szczegółów miejsca. Cena taryfy „za żądanie” w połączeniu z interfejsem Geocoding API jest bardziej opłacalna niż taryfa „za sesję” (obejmująca poszczególne sesje), jeśli są spełnione 2 z tych warunków:

• Jeśli interesuje Cię tylko szerokość geograficzna, długość geograficzna lub adres wybranego miejsca przez użytkownika, interfejs Geocoding API dostarczy te informacje w mniejszym stopniu niż wywołanie interfejsu PlaceDetails.
• Jeśli użytkownicy wybierają podpowiedzi autouzupełniania w ramach średnio 4 lub mniej żądań, cena za żądanie może być bardziej opłacalna niż cena za sesję.

Aby wybrać implementację Autouzupełniania miejsc dopasowaną do Twoich potrzeb, kliknij kartę odpowiadającą Twojej odpowiedzi na to pytanie.

Czy Twoja aplikacja wymaga jakichkolwiek informacji oprócz adresu i szerokości geograficznej/długości geograficznej wybranej prognozy?

Tak, potrzebuję więcej informacji

Korzystaj z autouzupełniania miejsc opartego na sesji, korzystając z szczegółów miejsca.
Twoja aplikacja wymaga informacji o miejscach, takich jak nazwa miejsca, status firmy lub godziny otwarcia, dlatego wdrożenie autouzupełniania miejsc powinno korzystać z tokena sesji (automatycznie lub wbudowanego w widżety JavaScript, Android lub iOS.Ich łączny koszt wynosi 0,017 USD za sesję i dodatkowe kody SKU danych miejsc w zależności od tego, o jakie pola danych miejsc prosisz}.

Wdrażanie widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Android i iOS. Obejmuje to zarówno żądania autouzupełniania miejsca, jak i żądanie informacji o wybranym miejscu. Określ parametr fields, aby mieć pewność, że żądania są wysyłane wyłącznie umieścić w odpowiednim miejscu pola danych.

Wdrażanie automatyczne
Używaj tokenu sesji w żądaniach autouzupełniania miejsc. Gdy żądasz szczegółów miejsca dotyczących wybranej prognozy, uwzględnij te parametry:

1. Identyfikator miejsca z odpowiedzi na żądanie autouzupełniania miejsc
2. token sesji użyty w żądaniu autouzupełniania miejsc;
3. Parametr fields określający rozmieść pola danych, których potrzebujesz,

Nie, potrzebny jest tylko adres i lokalizacja

W zależności od skuteczności korzystania z autouzupełniania miejsc interfejs Geocoding API może być dla Twojej aplikacji bardziej opłacalny niż interfejs Place Details. Skuteczność autouzupełniania każdej aplikacji różni się w zależności od tego, co wpisują użytkownicy, gdzie aplikacja jest używana i czy wdrożone zostały sprawdzone metody dotyczące optymalizacji wydajności.

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

Czy Twoi użytkownicy wybierają prognozę Miejsca w autouzupełnianiu po 4 lub mniej zapytaniach?

Tak

Zaimplementuj automatyczne uzupełnianie nazw miejsc za pomocą kodu, bez tokenów sesji, i wywołaj interfejs Geocoding API w przypadku wybranej prognozy miejsca.
Geocoding API dostarcza adresy oraz współrzędne szerokości i długości geograficznej za 0,005 USD na żądanie. Utworzenie 4 żądań typu Place Autocomplete – Per Request (Autouzupełnianie – według żądania) kosztuje 0,01132 USD, więc łączny koszt 4 żądań plus wywołania Geocoding API dla wybranej prognozy miejsca wynosi 0,01632 USD, czyli mniej niż cena autouzupełniania na sesję, która wynosi 0,017 USD za sesję¹.

Zastanów się nad skorzystaniem ze sprawdzonych metod dotyczących skuteczności, aby pomóc użytkownikom uzyskać podpowiedź, której szukają, przy użyciu jeszcze mniejszej liczby znaków.

Nie

Używaj autouzupełniania miejsc na podstawie sesji z informacjami o miejscach.
Średnia liczba spodziewanych żądań, które zostaną wysłane przed wybraniem podpowiedzi autouzupełniania miejsca, przekracza koszt ceny za sesję. Dlatego Twoja implementacja autouzupełniania miejsc powinna korzystać z tokenu sesji zarówno dla żądań autouzupełniania miejsc, jak i powiązanych z nimi żądań informacji o miejscach. Ich łączny koszt to 0,017 USD za sesję¹.

Wdrażanie widżetów
Zarządzanie sesjami jest automatycznie wbudowane w widżety JavaScript, Android i iOS. Obejmuje to zarówno żądania autouzupełniania miejsc, jak i żądania szczegółów miejsca dotyczące wybranej prognozy. Pamiętaj, by określić parametr fields, aby mieć pewność, że żądanie dotyczy tylko pól danych podstawowych.

Wdrażanie automatyczne
Używaj tokenu sesji w żądaniach autouzupełniania miejsc. Gdy żądasz szczegółów miejsca dotyczących wybranej prognozy, podaj te parametry:

1. identyfikator miejsca z odpowiedzi autouzupełniania miejsca,
2. token sesji użyty w żądaniu autouzupełniania miejsc;
3. parametr fields określający pola Dane podstawowe, takie jak adres i geometria;

Rozważ opóźnianie wysyłania żądań do usługi Autocomplete miejsc
Możesz stosować strategie takie jak opóźnianie wysyłania żądań do usługi Autocomplete miejsc do momentu, gdy użytkownik wpisze pierwsze 3 lub 4 znaki, aby Twoja aplikacja wysyłała mniej żądań. Na przykład wysyłanie zapytań do Autocomplete w usłudze Places po wpisaniu przez użytkownika 3 znaku oznacza, że jeśli użytkownik wpisze 7 znaków, a potem wybierze przewidywaną wartość, dla której wysyłasz 1 zapytanie do interfejsu Geocoding API, łączny koszt wyniesie 0,01632 USD (4 × 0,00283 USD za każde zapytanie do Autocomplete + 0,005 USD za geokodowanie).¹

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań automatyzacji spadnie poniżej 4, postępuj zgodnie ze wskazówkami dotyczącymi skutecznej implementacji autouzupełniania miejsc za pomocą interfejsu Geocoding API. Pamiętaj, że opóźnienie żądań może być postrzegane jako opóźnienie przez użytkownika, który może oczekiwać podpowiedzi po każdym naciśnięciu klawisza.

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

---

1. Koszty podane w tym miejscu są podane w USD. Pełne ceny znajdziesz na stronie płatności za Google Maps Platform.

Sprawdzone metody zwiększania skuteczności

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

• Dodaj ograniczenia dotyczące kraju, preferencje dotyczące lokalizacji oraz (w przypadku implementacji programowych) preferencje językowe do implementacji funkcji Autouzupełniania miejsc. Nie musisz wybierać języka dzięki widżetom, które wybierają język z przeglądarki użytkownika lub urządzenia mobilnego.
• Jeśli autouzupełnianie miejsc jest wyświetlane z mapą, możesz dostosować lokalizację do widoku mapy.
• W sytuacjach, gdy użytkownik nie wybierze żadnej z podpowiedzi autouzupełniania, ponieważ żadna z nich nie jest pożądanym adresem, możesz ponownie użyć oryginalnego danych wejściowych użytkownika, aby uzyskać bardziej trafne wyniki:
  • Jeśli oczekujesz, że użytkownik poda tylko adres, użyj pierwotnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli spodziewasz się, że użytkownicy będą wpisywać zapytania dotyczące konkretnego miejsca po nazwie lub adresie, skorzystaj z prośby o znajdowanie miejsca. Jeśli wyniki mają być uzyskiwane tylko w konkretnym regionie, użyj ustawienia lokalizacji.
  . Inne sytuacje, w których najlepiej użyć interfejsu Geocoding API, to:
  • Użytkownicy wpisujący adresy podrzędne w krajach, w których autouzupełnianie adresów miejsc jest niepełne, np. w Czechach, Estonii i na Litwie. Na przykład parametr Adres czeski „Stroupežnického 3191/17, Praha” daje częściową prognozę w miejscu Autouzupełnianie.
  • Użytkownicy wpisujący adresy z prefiksami odcinków dróg, np. „23-30 29th St, Queens” w Nowym Jorku lub „47-380 Kamehameha Hwy, Kaneohe” na wyspie Kauai na Hawajach.

Rozwiązywanie problemów

Błędy mogą występować w aplikacji, jednak większość z nich są zwykle spowodowane błędami konfiguracji (na przykład użyto złego klucza interfejsu API, klucz API został nieprawidłowo skonfigurowany) lub limitu błędów (aplikacja przekroczyła limit). Więcej informacji o limitach znajdziesz w sekcji Ograniczenia dotyczące wykorzystania.

Błędy, które wystąpią w przypadku korzystania z elementów sterujących autouzupełniania, są zwracane w sekcji onActivityResult() oddzwonienie. Aby uzyskać wiadomość o stanie wyniku, zadzwoń pod numer Autocomplete.getStatus().