Autouzupełnianie miejsc

Wybierz platformę: Android iOS JavaScript Usługa internetowa

usługa autouzupełniania w pakiecie SDK Miejsc na Androida zwraca prognozy miejsc w odpowiedzi na zapytania użytkownika. Gdy użytkownik wpisuje tekst, usługa zwraca sugestie dotyczące miejsc, takich jak firmy, adresy, kody plus i ciekawe miejsca.

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

• Dodaj widżet autouzupełniania, aby skrócić czas programowania i zapewnić spójne środowisko użytkownika.
• Pozyskiwanie prognoz dotyczących miejsc za pomocą programów, aby zapewnić użytkownikom spersonalizowane wrażenia.

Dodawanie widżetu autouzupełniania

Widżet autouzupełniania to okno wyszukiwania z wbudowaną funkcją autouzupełniania. 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.

Dodanie widżetu autouzupełniania do aplikacji jest możliwe na 2 sposoby:

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

Opcja 1. Umieść fragment AutocompleteSupportFragment

Aby dodać AutocompleteSupportFragment do aplikacji:

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ą potrzebne, jeśli osadzasz fragment.

Uwaga: AutcompleteActivity nie należy uruchamiać bezpośrednio. Zamiast tego użyj intencji do uruchamiania Autocomplete (PlaceAutocomplete w bibliotece zgodności).

Aby uruchomić widżet automatycznego uzupełniania za pomocą intencji:

1. Użyj funkcji Autocomplete.IntentBuilder, aby utworzyć zamiar, przekazując żądany 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);

      

Jeśli używasz intencji do uruchamiania widżetu autouzupełniania, możesz wybrać tryb wyświetlania nakładki lub tryb pełnoekranowy. Na poniższych zrzutach ekranu widać poszczególne tryby wyświetlania:

Rysunek 1. Widżet autouzupełniania w trybie nakładki

Rysunek 2.: widget autouzupełniania w trybie PEŁNY EKRAN

Rejestrowanie wywołania zwrotnego po otrzymaniu wyniku intencji

Aby otrzymywać powiadomienie, gdy użytkownik wybierze miejsce, zdefiniuj element registerForActivityResult(), który uruchamia działanie i także obsługuje wynik, jak pokazano w tym przykładzie. Jeśli użytkownik wybrał prognozę, zostanie ona dostarczona w intencji zawartej w obiekcie wyniku. Ponieważ intencja została utworzona przez Autocomplete.IntentBuilder, metoda Autocomplete.getPlaceFromIntent() może wyodrębnić z niej obiekt Miejsce.

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 to zrobić, aplikacja musi uzyskać prognozy dotyczące miejsc w sposób programowy. Aplikacja może uzyskać listę przewidywanych nazw lub adresów miejsc z interfejsu Autocomplete API, wywołując interfejsPlacesClient.findAutocompletePredictions(), przekazując obiektFindAutocompletePredictionsRequestz tymi parametrami:

• Wymagany: ciąg query zawierający tekst wpisany przez użytkownika.
• Zalecane: AutocompleteSessionToken, który grupował fazy zapytania i wyboru w ramach wyszukiwania użytkownika w oddzielnej sesji na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierze miejsce.
• Zalecane: obiekt RectangularBounds, który określa zakresy szerokości i długości geograficznej, aby ograniczać wyniki do określonego regionu.
• Opcjonalnie: co najmniej 1 2-literowy kod kraju (ISO 3166-1, alfa-2), wskazujący kraj lub kraje, w których wyniki mają być ograniczone.

• 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. Użyj tego żądania, aby rozstrzygnąć wyniki, gdy określona lokalizacja może być niejednoznaczna.
  • 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ę, 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 FindAutocompletePredictionsResponsew formacie Task. Element 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. Zazwyczaj jest to nazwa miejsca. Przykłady: „Wieża Eiffla” i „123 Pitt Street”.
• getSecondaryText(CharacterStyle)zwraca tekst dodatkowy opisu miejsca. Jest to przydatne, na przykład jako drugi wiersz podczas wyświetlania przewidywań autouzupełniania. Przykłady: „Avenue Anatole France, Paryż, Francja” i „Sydney, Nowa Południowa Walia”.
• getPlaceId()zwraca identyfikator miejsca przewidywanego miejsca. Identyfikator miejsca to tekstowy identyfikator jednoznacznie identyfikujący miejsce, którego możesz użyć do ponownego pobrania obiektu Place. Więcej informacji o identyfikatorach miejsc w pakiecie SDK Miejsc na Androida znajdziesz w sekcji Szczegóły miejsca. Ogólne informacje o identyfikatorach miejsc znajdziesz w artykule Identyfikator miejsca – omówienie.
• getPlaceTypes()zwraca listę typów miejsc powiązanych z tym miejscem.
• getDistanceMeters() zwraca odległość w metrach na linii prostej między tym miejscem a punktem początkowym określonym 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ę zgodnie z zasadą dołożenia wszelkich starań. Po wysłaniu prośby o anulowanie nie otrzymasz odpowiedzi. Wydanie tokena anulowania NIE gwarantuje, że konkretne żądanie zostanie anulowane. Możesz nadal otrzymać opłatę za żądanie, nawet jeśli nie otrzymasz odpowiedzi.

Tokeny sesji

Na potrzeby rozliczeń tokeny sesji łączą fazy zapytania i wyboru w autouzupełnianiu wyszukiwania w jedną sesję. Sesja rozpoczyna się, gdy użytkownik zacznie wpisywać zapytanie, a kończy, gdy wybierze miejsce. Każda sesja może zawierać wiele zapytań, po których następuje wybór jednego miejsca. Po zakończeniu sesji token staje się nieważny. Aplikacja musi wygenerować nowy token na każdą sesję. Zalecamy używanie tokenów sesji we wszystkich programowych sesjach autouzupełniania (gdy umieszczasz fragment lub uruchamiasz autouzupełnianie za pomocą intencji, interfejs API automatycznie się tym zajmie).

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 tokenach sesji

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. Możesz zastosować te ograniczenia do aktywności autouzupełniania, AutocompleteSupportFragmenti automatyzacji interfejsów API 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 z określonego regionu, wywołaj funkcję setLocationRestriction() (zwrócone zostaną tylko wyniki z określonego regionu).
• Aby zwrócić tylko wyniki zgodne z określonym typem miejsca, wywołaj funkcję setTypesFilter() (na przykład podanie wartości 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 2-literowe kody krajów zgodne ze standardem ISO 3166-1 alfa-2.

kierowanie wyników na określony region;

Aby zastosować autouzupełnianie w określonym regionie geograficznym, wywołaj funkcję setLocationBias(), podając parametr RectangularBounds. Poniższy przykład kodu pokazuje wywołanie funkcji setLocationBias() w przypadku wystąpienia fragmentu, aby zastosować sugestie autouzupełniania w regionie 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. Poniższy przykład kodu pokazuje wywołanie setLocationRestriction() w przypadku instancji fragmentu, aby zastosować sugestie autouzupełniania w regionie Sydney w 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 kolekcji typu

Możesz ograniczyć wyniki wyszukiwania automatycznego, aby wyświetlały tylko określone typy miejsc. 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 wskaż maksymalnie 5 wartości parametru type z tabeli 1 i tabeli 2, które podano w sekcji Typy miejsc. Wartości typu są zdefiniowane przez stałe w PlaceTypes.

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

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

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

      

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

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

      

Filtrowanie wyników według kraju

Aby filtrować wyniki autouzupełniania do maksymalnie 5 krajów, wywołaj funkcję setCountries(), aby ustawić kod kraju. Następnie prześlij filtr do fragmentu lub zamiaru. Kraje muszą być podawane jako 2-literowe kody krajów zgodne ze standardem ISO 3166-1 alfa-2.

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). Nadal obowiązują jednak te limity wykorzystania:

• Limit szybkości to 6000 QPM (żądań na minutę). Jest ona obliczana jako suma żądań po stronie klienta i po stronie serwera dla wszystkich aplikacji korzystających z danych uwierzytelniających tego samego projektu.

Wyświetlanie atrybucji w 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 po uzyskaniu miejsca docelowego na podstawie identyfikatora pobierzesz i wyświetlisz dodatkowe informacje o miejscu docelowym, musisz też wyświetlić atrybuty zewnętrzne.

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ć możliwości usługi Autouzupełnianie miejsc.

Oto kilka ogólnych wskazówek:

• Najszybszym sposobem na stworzenie działającego interfejsu użytkownika jest użycie: widżetu autouzupełniania Maps JavaScript API, Widżetu autouzupełniania z pakietu SDK Miejsc na Androida lub Widżetu autouzupełniania z pakietu SDK Miejsc na iOS.
• Na początku zaznaj się z najważniejszymi polami danych usługi Autouzupełnianie miejsc.
• Pola preferencji lokalizacji i ograniczeń lokalizacji są opcjonalne, ale mogą mieć znaczący wpływ na działanie funkcji 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 obsługuje przypadki, gdy nie ma wyboru, i oferuje użytkownikom sposób na kontynuowanie.

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ż automatyczne wdrażanie funkcji Autocomplete miejsc, aby uzyskać dostęp do cen za prośbę i wysłać wyniki interfejsu Geocoding API dotyczące wybranego miejsca zamiast Szczegółów miejsca. Cena naliczona na żądanie w połączeniu z interfejsem Geocoding API jest bardziej opłacalna niż cena naliczona na sesję (o partycji), jeśli są spełnione obie te przesłanki:

• 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ą prognozę autouzupełniania w ramach średnio 4 lub mniej żądań prognozy autouzupełniania, 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

Używaj autouzupełniania miejsc na podstawie sesji z informacjami o miejscach.
Twoja aplikacja wymaga szczegółów miejsca, takich jak nazwa miejsca, stan firmy lub godziny otwarcia, dlatego implementacja autouzupełniania miejsc powinna używać tokenu sesji (programowo lub wbudowanego w widżety JavaScript, Android lub iOS), za co płacisz 0,017 USD za sesję plus odpowiedni SKU danych miejsc w zależności od tego, których pól danych miejsc używasz.¹

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 dotyczące miejsc, jak i żądanie informacji o wybranym miejscu. Pamiętaj, aby określić parametr fields, aby mieć pewność, że przesyłasz tylko pola danych o miejscach, których potrzebujesz.

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 autouzupełnianie miejsc
2. token sesji użyty w żądaniu autouzupełniania miejsc.
3. Parametr fields określający pola danych o miejscach, których potrzebujesz

Nie, potrzebny jest tylko adres i lokalizacja

W zależności od skuteczności korzystania z automatycznego uzupełniania adresów miejsc docelowych interfejs API geokodowania może być dla Twojej aplikacji bardziej opłacalny niż usługa Szczegóły miejsc docelowych. Skuteczność funkcji Autouzupełnianie w każdej aplikacji zależy od tego, co wpisują użytkownicy, gdzie jest używana aplikacja i czy zostały zastosowane sprawdzone metody optymalizacji skuteczności.

Aby odpowiedzieć na to pytanie, sprawdź, ile znaków użytkownik wpisze średnio przed wybraniem prognozy Miejsca w aplikacji.

Czy Twoi użytkownicy wybierają prognozę Miejsca w autouzupełnianiu po co najmniej 4 żądaniach?

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 i współrzędne szerokości i długości geograficznej za 0,005 USD za każde zapytanie. Przesyłanie 4 żądań autouzupełniania miejsc – na żądanie kosztuje 0,01132 USD, więc łączny koszt 4 żądań plus wywołania interfejsu Geocoding API dotyczącego wybranego miejsca wyniesie 0,01632 USD, co jest niższe niż cena autouzupełniania na sesję wynosząca 0,017 USD na sesję.¹

Rozważ zastosowanie sprawdzonych metod dotyczących wydajności, aby pomóc użytkownikom uzyskać oczekiwane wyniki w jeszcze krótszym formacie.

Nie

Używaj autouzupełniania miejsc na podstawie sesji z informacjami o miejscach.
Ponieważ średnia liczba żądań, które według Twoich przewidywań zostaną wysłane, zanim użytkownik wybierze przewidywanie autouzupełniania miejsc, przekroczy koszt ustalany na podstawie sesji, implementacja autouzupełniania miejsc powinna używać tokena sesji zarówno do żądań autouzupełniania miejsc, jak i powiązanego żądania szczegółów miejsca.Oznacza to łączny koszt 0,017 USD na 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 dotyczące miejsc, jak i żądanie informacji o wybranym miejscu. Pamiętaj, aby określić parametr fields, aby mieć pewność, że żądasz tylko pól Dane podstawowe.

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 autouzupełnianie miejsc
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 próśb o wyszukiwanie automatyczne w usłudze Place po wpisaniu przez użytkownika 3 znaków oznacza, że jeśli użytkownik wpisze 7 znaków, a potem wybierze przewidywaną odpowiedź, dla której wysyłasz 1 żądanie interfejsu Geokodowanie API, łączny koszt wyniesie 0,01632 USD (4 × 0,00283 USD za każde żądanie dotyczące automatycznego wyszukiwania + 0,005 USD za geokodowanie).¹

Jeśli opóźnienie żądań może spowodować, że średnia liczba żądań programowych będzie niższa niż 4, możesz postępować zgodnie z instrukcjami dotyczącymi skutecznego korzystania z interfejsu Place Autocomplete API z użyciem interfejsu Geocoding API. Pamiętaj, że opóźnianie żądań może być odbierane przez użytkownika jako opóźnienie, ponieważ może on oczekiwać wyświetlania prognoz przy każdym nowym 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 informacje o cenach znajdziesz na stronie Płatności za korzystanie z Google Maps Platform.

Sprawdzone metody dotyczące wydajności

W tych wytycznych znajdziesz wskazówki dotyczące optymalizacji działania autouzupełniania w Google Maps:

• Dodaj ograniczenia dotyczące kraju, preferencje dotyczące lokalizacji oraz (w przypadku implementacji programowych) preferencje językowe do implementacji automatycznego uzupełniania miejsc. W przypadku widżetów nie trzeba podawać preferencji językowych, ponieważ są one pobierane z przeglądarki lub urządzenia mobilnego użytkownika.
• Jeśli autouzupełnianie miejsc jest wyświetlane z mapą, możesz dostosować lokalizację do widoku mapy.
• Jeśli 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 informacje o adresie, ponownie użyj pierwotnych danych wejściowych użytkownika w wywołaniu interfejsu Geocoding API.
  • Jeśli oczekujesz, że użytkownik będzie wpisywać zapytania dotyczące konkretnego miejsca według nazwy lub adresu, użyj żądania znajdowania miejsca. Jeśli wyniki mają być uzyskiwane tylko w konkretnym regionie, użyj ustawienia lokalizacji.
  Inne scenariusze, w których warto użyć interfejsu Geocoding API:
  • Użytkownicy wpisują adresy pomieszczeń w budynku, np. adresy konkretnych lokali lub apartamentów. Na przykład czeski adres „Stroupežnického 3191/17, Praha” daje częściową podpowiedź w autouzupełnianiu adresów.
  • Użytkownicy wpisujący adresy z prefiksami segmentó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

Chociaż może wystąpić wiele różnych błędów, większość z nich jest zwykle spowodowana błędami konfiguracji (np. użyto nieprawidłowego klucza API lub klucz API został źle skonfigurowany) lub błędami dotyczącymi limitu (aplikacja przekroczyła swój limit). Więcej informacji o limitach znajdziesz w sekcji Ograniczenia wykorzystania.

Błędy występujące podczas korzystania z ustawień autouzupełniania są zwracane w wywołaniu funkcji onActivityResult(). Aby uzyskać wiadomość o stanie wyniku, zadzwoń pod numer Autocomplete.getStatus().