Autouzupełnianie (nowość)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Autouzupełnianie (nowość) zwraca prognozy dotyczące miejsc w odpowiedzi na żądanie zawierające ciąg wyszukiwania tekstowego i granice geograficzne, które kontrolują obszar wyszukiwania. Autouzupełnianie może dopasowywać całe słowa i podłańcuchy danych wejściowych oraz rozpoznawać nazwy miejsc, adresy i kody plus. Aplikacja może wysyłać zapytania w miarę wpisywania zapytania przez użytkownika, aby na bieżąco zapewniać prognozy dotyczące miejsc i zapytań.

Na przykład wywołujesz autouzupełnianie, używając jako danych wejściowych ciągu znaków zawierającego częściowe dane wprowadzone przez użytkownika: „piz sycylijski”, a obszar wyszukiwania jest ograniczony do San Francisco w stanie Kalifornia. Odpowiedź zawiera listę przewidywanych miejsc, które pasują do ciągu wyszukiwania i obszaru wyszukiwania, np. nazwę restauracji o nazwie „Sycylijska pizza”.

Zwracane prognozy dotyczące miejsc są wyświetlane użytkownikowi i pomagają mu w wyborze odpowiedniego miejsca. Możesz wysłać żądanie Szczegóły miejsca (nowe), aby uzyskać więcej informacji o dowolnych zwróconych prognozach dotyczących miejsc.

Uwaga: autouzupełnianie (nowość) jest dostępne w pakiecie SDK Miejsc na Androida w wersji 3.5.0 lub nowszej. Więcej informacji znajdziesz w artykule Wybieranie wersji pakietu SDK.

Żądania autouzupełniania (nowe)

Aplikacja może uzyskać listę przewidywanych nazw miejsc lub adresów z interfejsu API autouzupełniania, wywołując metodę PlacesClient.findAutocompletePredictions() i przekazując obiekt FindAutocompletePredictionsRequest. Poniższy przykład zawiera pełne wywołanie funkcji PlacesClient.findAutocompletePredictions().

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();
LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);
final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Sicilian piz")
            .setRegionCode("ES")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Uwaga: połączenia wykonywane za pomocą widżetów autouzupełniania miejsc zawsze wywołują funkcję Place Autouzupełnianie, a nie autouzupełnianie miejsca (Nowe); metoda inicjowania nie ma wpływu na wywołania widżetów.

CancellationToken pozwala anulować żądanie wysłane do dowolnej z klas żądania (na przykład FetchPlaceRequest). Anulowanie odbywa się z najwyższą starannością. Po wysłaniu prośby o anulowanie nie otrzymasz odpowiedzi. Wystawienie tokena anulowania NIE gwarantuje anulowania danego żądania i może zostać naliczona opłata, nawet jeśli nie otrzymasz odpowiedzi.

Autouzupełnianie (nowe) odpowiedzi

Interfejs API zwraca wartość FindAutocompletePredictionsResponse w Task. FindAutocompletePredictionsResponse zawiera listę maksymalnie 5 obiektów AutocompletePrediction reprezentujących przewidywane miejsca. Jeśli nie istnieje znane miejsce odpowiadające zapytaniu i kryteriom filtra, lista może być pusta.

W przypadku każdego przewidywanego miejsca możesz wywołać następujące metody, aby pobrać informacje o miejscu:

• getFullText(CharacterStyle) zwraca pełny tekst opisu miejsca. To połączenie tekstu głównego i dodatkowego. Przykład: „Wieża Eiffla, aleja Anatole'a France'a, Paryż, Francja”. Ta metoda pozwala dodatkowo wyróżnić sekcje tekstu, które pasują do wyszukiwania, z wybranym stylem, za pomocą metody CharacterStyle. Parametr CharacterStyle jest opcjonalny. Jeśli nie potrzebujesz żadnego podświetlania, ustaw go na wartość null.
• getPrimaryText(CharacterStyle) zwraca główny tekst opisujący miejsce. Jest to zwykle nazwa miejsca. Przykłady: „Wieża Eiffla” i „123 Pitt Street”.
• getSecondaryText(CharacterStyle) zwraca tekst podmiotu zależnego opisu miejsca. Jest to przydatne na przykład jako drugi wiersz dla podpowiedzi autouzupełniania. Przykłady: „A Avenue Anatole France, Paryż, Francja” i „Sydney, Nowa Południowa Walia”.
• getPlaceId() zwraca identyfikator przewidywanego miejsca. Identyfikator miejsca to tekstowy identyfikator, który jednoznacznie identyfikuje miejsce. Możesz go później użyć, aby ponownie pobrać obiekt Place. Więcej informacji o identyfikatorach miejsc w autouzupełnianiu znajdziesz w artykule Szczegóły miejsca (nowość). Ogólne informacje o identyfikatorach miejsc znajdziesz w artykule Omówienie identyfikatora miejsca.
• getTypes() zwraca listę typów miejsc powiązanych z tym miejscem.
• getDistanceMeters() zwraca prostą odległość wyrażoną w metrach między tym miejscem a źródłem określonym w żądaniu.

Wymagane parametry

• Zapytanie

  Ciąg tekstowy, który ma być przeszukiwany. Określ pełne słowa i podłańcuchy, nazwy miejsc, adresy i kody plus. Usługa autouzupełniania (nowa) zwraca dopasowania kandydatów na podstawie tego ciągu znaków i porządkuje wyniki na podstawie ich postrzeganej trafności.

  Aby ustawić parametr zapytania, podczas tworzenia obiektu FindAutocompletePredictionsRequest wywołaj metodę setQuery().

Parametry opcjonalne

• Typy główne

  Lista maksymalnie 5 wartości typów z typów Tabela A lub Tabela B używanych do filtrowania miejsc zwróconych w odpowiedzi. Miejsce musi pasować do jednej z określonych wartości typu podstawowego, aby można było uwzględnić je w odpowiedzi.

  Miejsce może mieć tylko 1 typ podstawowy z typów Tabela A lub Tabela B, które są z nim powiązane. Typem głównym może być np. "mexican_restaurant" lub "steak_house".

  Żądanie zostanie odrzucone z powodu błędu INVALID_REQUEST, jeśli:

  • Określono więcej niż 5 typów.
  • Wszystkie nierozpoznane typy są określone.

  Aby ustawić parametr typów głównych, wywołaj metodę setTypesFilter() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

• Kraje

  Uwzględniaj tylko wyniki z określonej listy krajów, która zawiera maksymalnie 15 dwuznakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli go pominiesz, do odpowiedzi nie będą stosowane żadne ograniczenia. Aby na przykład ograniczyć regiony do Niemiec i Francji:

  Jeśli podasz zarówno locationRestriction, jak i includedRegionCodes, wyniki będą znajdować się w obszarze przecięcia tych ustawień.

  Aby ustawić parametr krajów, wywołaj metodę setCountries() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

• Przesunięcie danych wejściowych

  Przesunięcie znaków Unicode liczone od zera, które wskazuje pozycję kursora w zapytaniu. Pozycja kursora może wpływać na wyświetlane podpowiedzi. Jeśli pole jest puste, domyślnie stosowana jest długość zapytania.

  Aby ustawić parametr przesunięcia wejściowego, wywołaj metodę setInputOffset() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

• Korekta lokalizacji lub ograniczenie lokalizacji

  Aby zdefiniować obszar wyszukiwania, możesz określić promowanie przez lokalizację lub ograniczenie lokalizacji, ale nie oba te tryby. Ograniczenie lokalizacji odnosi się do określania regionu, w którym muszą się znajdować wyniki, a zniekształcenia lokalizacji – do określenia regionu, w którym muszą znajdować się wyniki. Główna różnica polega na tym, że przy odchyleniach od lokalizacji wyniki spoza określonego regionu nadal mogą być zwracane.

  • Korekta lokalizacji

    Określa obszar wyszukiwania. Ta lokalizacja działa odchylenia, a nie jako ograniczenie, dlatego wyniki spoza określonego obszaru mogą nadal być zwracane.

    Aby ustawić parametr odchylenia lokalizacji, wywołaj metodę setLocationBias() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

  • Ograniczenie dotyczące lokalizacji

    Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie będą zwracane.

    Aby ustawić parametr ograniczenia lokalizacji, wywołaj metodę setLocationRestriction() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

  Określ uprzedzenia lokalizacji lub region ograniczenia lokalizacji jako prostokątny widoczny obszar lub koło.

  • Okrąg jest wyznaczany przez punkt środkowy i promień w metrach. Promień musi mieścić się w zakresie od 0,0 do 50 000,0 włącznie. Wartością domyślną jest 0,0. W przypadku ograniczenia lokalizacji ustaw promień na wartość większą niż 0,0. W przeciwnym razie żądanie nie zwraca żadnych wyników.

  • Prostokąt to widoczny obszar o długości i szerokości geograficznej przedstawiony jako dwa przeciwległe punkty low i high po przekątnej. Widoczny obszar jest uważany za obszar zamknięty, co oznacza, że obejmuje swoją granicę. Granice szerokości geograficznej muszą mieścić się w przedziale od -90 do 90 stopni włącznie, a granice długości geograficznej od -180 do 180 stopni włącznie:

    Uwaga: obsługiwane typy uprzedzeń różnią się w zależności od używanej wersji pakietu SDK. Funkcja CircularBounds jest dostępna tylko w funkcji autouzupełniania (nowość).
    • Jeśli low = high, widoczny obszar składa się z tego pojedynczego punktu.
    • Jeśli low.longitude > high.longitude, zakres długości geograficznej jest odwrócony (widoczny obszar przecina linię długości geograficznej 180 stopni).
    • Jeśli low.longitude = –180 stopni, a high.longitude = 180 stopni, widoczny obszar obejmuje wszystkie długości geograficzne.
    • Jeśli low.longitude = 180 stopni, a high.longitude = -180 stopni, zakres długości geograficznej jest pusty.

    Zarówno pole low, jak i high muszą być wypełnione, a reprezentowane pole nie może być puste. Gdy to zrobisz, pojawi się błąd.

• Punkt początkowy

  Punkt początkowy, z którego należy obliczyć odległość prostą do miejsca docelowego (dostępny za pomocą getDistanceMeters()). Jeśli ta wartość zostanie pominięta, odległość liniowa nie zostanie zwrócona. Wartość należy podać jako szerokość i długość geograficzną:

  Aby ustawić parametr punktu początkowego, wywołaj metodę setOrigin() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

• Kod regionu

  Kod regionu używany do formatowania odpowiedzi wraz z formatowaniem adresu podany jako dwuznakowa wartość ccTLD („domena najwyższego poziomu”). Większość kodów ccTLD jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Wielka Brytania i Irlandia Północna”).

  Uwaga: kod regionu ma odzwierciedlać region, z którego pochodzi żądanie, a nie region docelowy zapytania.

  Jeśli podasz nieprawidłowy kod regionu, interfejs API zwróci błąd INVALID_ARGUMENT. Ten parametr może wpływać na wyniki w zależności od obowiązującego prawa.

  Aby ustawić parametr kodu regionu, wywołaj metodę setRegionCode() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

• Token sesji

  Tokeny sesji to ciągi wygenerowane przez użytkownika, które śledzą wywołania autouzupełniania (nowe) jako „sesje”. Autouzupełnianie używa tokenów sesji do grupowania faz zapytania i wyboru fazy wyszukiwania autouzupełniania przez użytkownika w oddzielną sesję na potrzeby rozliczeń. Sesja rozpoczyna się, gdy użytkownik zaczyna wpisywać zapytanie, a kończy się, 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 straci ważność, a aplikacja musi wygenerować nowy token dla każdej sesji. Zalecamy używanie tokenów sesji we wszystkich sesjach automatycznego autouzupełniania (gdy umieścisz fragment lub uruchomisz autouzupełnianie za pomocą intencji, interfejs API zajmie się tym automatycznie).

  Autouzupełnianie identyfikuje każdą sesję przy użyciu identyfikatora AutocompleteSessionToken. Aplikacja powinna przekazywać nowy token sesji przy rozpoczynaniu każdej nowej sesji, a następnie przekazywać ten sam token wraz z identyfikatorem miejsca w kolejnym wywołaniu funkcji fetchPlace(), aby pobrać informacje o miejscu wybranym przez użytkownika.

  Aby ustawić parametr tokena sesji, wywołaj metodę setSessionToken() podczas tworzenia obiektu FindAutocompletePredictionsRequest.

  Więcej informacji znajdziesz w artykule o tokenach sesji.

Przykłady autouzupełniania (nowe)

Użyj ograniczenia lokalizacji i promowania lokalizacji

Autouzupełnianie (nowość) do kontrolowania obszaru wyszukiwania wykorzystuje domyślnie promowanie adresu IP. W przypadku promowania ze względu na adres IP interfejs API używa adresu IP urządzenia do promowania wyników. Aby określić obszar do wyszukiwania, możesz opcjonalnie skorzystać z ograniczenia lokalizacji lub umiejętności związanych z lokalizacją (ale nie z obu tych rozwiązań).

Ograniczenie lokalizacji określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W poniższym przykładzie użyto ograniczenia lokalizacji, aby ograniczyć żądanie do okrągłego ograniczenia lokalizacji z promieniem 5000 metrów wyśrodkowanym na San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

W przypadku uprzedzenia lokalizacji lokalizacja działa jako odchylenie, co oznacza, że mogą być zwracane wyniki dotyczące wskazanej lokalizacji, łącznie z wynikami spoza określonego obszaru. W następnym przykładzie zmieniamy poprzednie żądanie tak, by używało uprzedzeń związanych z lokalizacją:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Użyj typów głównych

Aby ograniczyć wyniki żądania do określonego typu, zgodnie z tabelą A i tabelą B użyj parametru typy główne. Możesz określić tablicę zawierającą maksymalnie 5 wartości. Jeśli nazwa zostanie pominięta, zwracane są wszystkie typy.

Poniższy przykład określa ciąg zapytania „Piłka nożna” i używa głównego parametru typów, aby ograniczyć wyniki do instytucji typu "sporting_goods_store":

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store");

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Soccer")
            .setIncludedPrimaryTypes(primaryTypes)
            .setLocationBias(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Jeśli pominiesz parametr typów głównych, wyniki mogą zawierać instytucje określonego typu, np. "athletic_field".

Użyj punktu początkowego

Jeśli umieścisz w żądaniu parametr origin, który jest podawany jako współrzędne szerokości i długości geograficznej, interfejs API uwzględnia w odpowiedzi odległość prostą od punktu początkowego do miejsca docelowego (dostępne za pomocą getDistanceMeters()). W tym przykładzie ustawiamy początek środka San Francisco:

Places.initializeWithNewPlacesApiEnabled(context, apiKey);
final List<Field> placeFields = getPlaceFields();

LatLng center = new LatLng(37.7749, -122.4194);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000);

final FindAutocompletePredictionsRequest autocompletePlacesRequest =
    FindAutocompletePredictionsRequest.builder()
            .setQuery("Amoeba")
            .setOrigin(center)
            .setLocationRestriction(circle)
            .build());
placesClient.findAutocompletePredictions(autoCompletePlacesRequest)
    .addOnSuccessListener(
        (response) -> {
            List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions();
          }
    ).addOnFailureListener(
        exception -> {
            Log.e(TAG, "some exception happened" + exception.getMessage());
        })
    );

Atrybucje

Z autouzupełniania (nowego) możesz korzystać nawet bez mapy. Jeśli jest wyświetlana mapa, musi to być mapa Google. Gdy wyświetlasz podpowiedzi z usługi autouzupełniania (nowość) bez mapy, w polu wyszukiwania lub wynikach wyszukiwania musisz umieścić logo Google. Więcej informacji znajdziesz w artykule Wyświetlanie logo i atrybucji Google.