Autouzupełnianie (nowość)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Autouzupełnianie (nowa wersja) zwraca prognozy miejsc w odpowiedzi na żądanie, które zawiera ciąg tekstowy wyszukiwania i granice geograficzne kontrolujące obszar wyszukiwania. Autouzupełnianie może dopasowywać całe słowa i podciągi wejściowe, rozwiązując nazwy miejsc, adresy i kody pocztowe. Aplikacja może wysyłać zapytania w miarę wpisywania przez użytkownika tekstu, aby na bieżąco wyświetlać prognozy dotyczące miejsc i zapytań.

Na przykład wywołujesz funkcję autouzupełniania, podając jako dane wejściowe ciąg znaków zawierający częściowe dane wejściowe użytkownika „Sicilian piz”, z obszarem wyszukiwania ograniczonym do San Francisco w Kalifornii. Odpowiedź zawiera listę prognozowanych miejsc pasujących do ciągu znaków i obszaru wyszukiwania, np. restaurację o nazwie „Sicilian Pizza Kitchen”.

Zwrócone prognozy miejsc są przeznaczone do wyświetlenia użytkownikowi, aby ułatwić mu wybór pożądanego miejsca. Aby uzyskać więcej informacji o dowolnym z zwróconych przewidywanych miejsc, możesz wysłać żądanie Szczegóły miejsca (nowe).

Uwaga: funkcja Autouzupełnianie (nowa) jest dostępna w pakiecie SDK Miejsca w wersji 3.5.0 i nowszych na Androida. Więcej informacji znajdziesz w artykule Wybieranie wersji pakietu SDK. Więcej informacji o korzystaniu z interfejsów API Kotlina dodanych w wersji 4.0.0 znajdziesz w omówieniu dokumentacji.

żądania autouzupełniania (nowe);

Aplikacja może uzyskać listę przewidywanych nazw miejsc lub adresów z interfejsu Autocomplete API, wywołując interfejs PlacesClient.findAutocompletePredictions(), przekazując obiekt FindAutocompletePredictionsRequest. Przykład poniżej pokazuje 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: wywołania wykonywane za pomocą widżetów Autouzupełnianie miejsca zawsze wywołują Autouzupełnianie miejsca, a nie Autouzupełnianie miejsca (nowa wersja); na wywołania widżetów nie ma wpływu metoda inicjalizacji.

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

Możesz użyć obiektu CancellationToken, aby spróbować anulować żądanie do dowolnej klasy żądań (na przykład FetchPlaceRequest). Anulowanie odbywa się zgodnie z zasadą możliwie najlepszej obsługi. 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.

Odpowiedzi na „Autouzupełnianie” (nowe)

Interfejs API zwraca FindAutocompletePredictionsResponsew Task. Obiekt FindAutocompletePredictionsResponse zawiera listę maksymalnie 5 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. Jeśli nie potrzebujesz podświetlania, ustaw tę wartość na null.
• 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 autouzupełnianiu znajdziesz w artykule Szczegóły miejsca (nowa wersja). Ogólne informacje o identyfikatorach miejsc znajdziesz w artykule Identyfikator miejsca – omówienie.
• getTypes()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.

Wymagane parametry

• Zapytanie

  Tekst, w którym ma być przeprowadzone wyszukiwanie. Określ pełne słowa i podciągi znaków, nazwy miejsc, adresy i kody pocztowe. Usługa Autocomplete (New) zwraca dopasowania na podstawie tego ciągu znaków i porządkuje wyniki według ich trafności.

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

Parametry opcjonalne

• Typy podstawowe

  Lista maksymalnie 5 wartości typu z tablic Table A lub Table B, która służy do filtrowania miejsc zwracanych w odpowiedzi. Aby miejsce zostało uwzględnione w odpowiedzi, musi odpowiadać jednej z podanych wartości typu podstawowego.

  Miejsce może mieć tylko jeden podstawowy typ z typów tabeli A lub tabeli B powiązanych z tym miejscem. Na przykład typ podstawowy może być "mexican_restaurant" lub "steak_house".

  Prośba zostanie odrzucona z błędem INVALID_REQUEST, jeśli:

  • Podano więcej niż 5 typów.
  • Wszelkie nierozpoznane typy są określane.

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

• Kraje

  Uwzględniaj tylko wyniki z listy określonych krajów, która jest listą maksymalnie 15-znakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli nie zostanie podany, nie zostaną zastosowane żadne ograniczenia odpowiedzi. Aby na przykład ograniczyć regiony do Niemiec i Francji:

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

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

• przesunięcie wejścia,

  Odsunięcie znaku Unicode od 0, wskazujące pozycję kursora w zapytaniu. Pozycja kursora może wpływać na prognozy zwracane przez model. Jeśli to pole jest puste, domyślnie zostanie użyta długość zapytania.

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

• Ustawienie preferencji dotyczących lokalizacji lub ograniczenie dotyczące lokalizacji

  Aby określić obszar wyszukiwania, możesz podać preferencje dotyczące lokalizacji lub ograniczenie lokalizacji, ale nie oba te ustawienia. Ograniczenie lokalizacji to określenie regionu, w którym muszą znajdować się wyniki, a uwzględnienie lokalizacji to określenie regionu, w pobliżu którego muszą znajdować się wyniki. Główna różnica polega na tym, że przy uwzględnieniu lokalizacji wyniki mogą być zwracane poza określony region.

  • Uwzględnianie lokalizacji

    Określa obszar wyszukiwania. Ta lokalizacja służy do ukierunkowania wyników, a nie do ich ograniczenia, więc wyniki poza określonym obszarem mogą być nadal zwracane.

    Aby ustawić parametr „location_bias”, podczas tworzenia obiektu FindAutocompletePredictionsRequest wywołaj metodę setLocationBias().

  • Ograniczenie dotyczące lokalizacji

    Określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane.

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

  Określ region z uwzględnieniem lokalizacji lub region z ograniczeniem lokalizacji jako prostokątny obszar widoczny lub okrąg.

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

  • Prostokąt to widoczny obszar z uwzględnieniem szerokości i długości geograficznej, reprezentowany przez 2 punkty low i high, które leżą na przekątnej. Widoczny obszar jest uważany za zamknięty obszar, co oznacza, że obejmuje swoją granicę. Granice szerokości geograficznej muszą mieścić się w przedziale od -90 do 90 stopni, a granice długości geograficznej – w przedziale od -180 do 180 stopni:

    Uwaga: obsługiwane typy zafałszowania różnią się w zależności od wersji pakietu SDK, z której korzystasz. CircularBounds jest dostępna tylko w Autouzupełnianiu (Nowa wersja).
    • 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°).
    • 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.

    Pola low i high muszą być wypełnione, a reprezentowane pole nie może być puste. Pusta wizjer prowadzi do błędu.

• Punkt początkowy

  Punkt początkowy, z którego obliczana jest odległość w linii prostej do miejsca docelowego (dostępny za pomocą parametru getDistanceMeters()). Jeśli ta wartość zostanie pominięta, odległość w linii prostej nie zostanie zwrócona. Musi być podany jako współrzędne szerokości i długości geograficznej:

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

• Kod regionu

  Kod regionu użyty do sformatowania odpowiedzi, w tym adresu, podany jako kod kraju domeny najwyższego poziomu („top-level domain”) o dwóch znakach. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1, z kilkoma wyjątkami. Na przykład ccTLD Wielkiej Brytanii to „uk” (.co.uk), a jej kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”).

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

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

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

• Token sesji

  Tokeny sesji to tworzone przez użytkownika ciągi znaków, które śledzą wywołania funkcji Autouzupełnianie (nowa) jako „sesje”. Autouzupełnianie używa tokenów sesji, aby grupować fazy zapytania i wyboru w wyszukiwaniu autouzupełniania użytkownika w oddzielne sesje na potrzeby rozliczeń. 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 traci ważność. Aplikacja musi wygenerować nowy token na każdą sesję. Zalecamy używanie tokenów sesji w przypadku wszystkich sesji automatycznego uzupełniania w ramach programowania (gdy umieszczasz fragment lub uruchamiasz automatyczne uzupełnianie za pomocą intencji, interfejs API zrobi to automatycznie).

  Autouzupełnianie 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 fetchPlace(), aby pobrać szczegóły miejsca wybranego przez użytkownika.

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

  Więcej informacji znajdziesz w artykule Tokeny sesji.

Przykłady autouzupełniania (nowa wersja)

Używanie ograniczeń dotyczących lokalizacji i uwzględniania lokalizacji

Autouzupełnianie (nowa wersja) domyślnie używa ukierunkowania adresu IP do kontrolowania obszaru wyszukiwania. W przypadku ukierunkowania na adres IP interfejs API używa adresu IP urządzenia, aby ukierunkować wyniki. Aby określić obszar wyszukiwania, możesz opcjonalnie użyć ograniczenia lokalizacji lub preferencji lokalizacji (nie obu jednocześnie).

Ograniczenie dotyczące lokalizacji określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W tym przykładzie użyliśmy ograniczenia dotyczącego lokalizacji, aby ograniczyć żądanie do koła o promieniu 5000 metrów z San Francisco jako środkiem:

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 użycia lokalizacji jako czynnika preferencji lokalizacja służy jako czynnik preferencji, co oznacza, że wyniki mogą być zwracane w pobliżu określonej lokalizacji, w tym poza nią. W następnym przykładzie zmieniamy poprzednie zapytanie, aby wykorzystać uczenie z uwzględnieniem lokalizacji:

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żywanie typów podstawowych

Użyj parametru primary_types, aby ograniczyć wyniki żądania do określonego typu wymienionego w tabeli A i tabeli B. Możesz podać tablicę zawierającą maksymalnie 5 wartości. Jeśli nie zostanie podany, zwrócone zostaną wszystkie typy.

W tym przykładzie łańcuch zapytania to „Soccer”, a parametr primarytypes służy do ograniczania wyników do obiektów 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 primary_types, wyniki mogą obejmować obiekty typu, którego nie chcesz, np. "athletic_field".

Użyj punktu początkowego

Jeśli w żądaniu podasz parametr origin podany jako współrzędne szerokości i długości geograficznej, interfejs API uwzględni w odpowiedzi odległość w linii prostej od punktu początkowego do docelowego (dostępny za pomocą parametru getDistanceMeters()). W tym przykładzie punkt początkowy to centrum 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

Możesz używać funkcji Autouzupełnianie (nowa) nawet bez mapy. Jeśli chcesz wyświetlić mapę, musi to być mapa Google. Jeśli wyświetlasz prognozy z usługi Autocomplete (Nowa) bez mapy, musisz uwzględnić logo Google wyświetlane w polu wyszukiwania lub w wynikach. Więcej informacji znajdziesz w artykule Wyświetlanie logo i tekstu atrybucji Google.