Autouzupełnianie (nowość)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Autouzupełnianie (nowość) zwraca podpowiedzi dotyczące miejsc w odpowiedź na żądanie, która zawiera ciąg wyszukiwania tekstowego i granice geograficzne które kontrolują obszar wyszukiwania. Autouzupełnianie może dopasowywać całe słowa i podciągi znaków w danych wejściowych, rozwiązując nazwy miejsc, adresy i kody pocztowe. Aplikacja może wysyłać zapytania które użytkownik wpisuje, i oferuje bieżący obraz miejsca oraz prognozy zapytań.

Na przykład wywołasz autouzupełnianie, używając jako danych wejściowych ciąg znaków zawierający częściowe dane wprowadzone przez użytkownika, „piz sycylijski” z obszarem wyszukiwania ograniczona do San Francisco, Kalifornia. Odpowiedź zawiera listę miejsc. podpowiedzi pasujące do wyszukiwanego hasła i obszaru wyszukiwania, np. restauracja o nazwie „Sycylijska pizza”.

Zwracane prognozy dotyczące miejsc mają być prezentowane użytkownikowi, aby ułatwić ich przy wyborze odpowiedniego 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 pakietu SDK wersji. Więcej informacje na temat korzystania z interfejsów API Kotlin dodanych w wersji 4.0.0, zapoznaj się z dokumentacją Omówienie

Prośby o autouzupełnianie (nowe)

Aplikacja może uzyskać listę przewidywanych nazw miejsc lub z interfejsu API autouzupełniania przez wywołanie PlacesClient.findAutocompletePredictions(), zaliczając FindAutocompletePredictionsRequest obiektu. Poniższy przykład zawiera pełne wywołanie 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 nawiązane przy użyciu autouzupełniania miejsc widżety zawsze wywołaj Place Autouzupełnianie, a nie miejsce Autouzupełnianie (nowość); na wywołania widżetu nie mają wpływu metody inicjowania.

Uwaga: więcej informacji o inicjowaniu PlacesClient znajdziesz tutaj Zainicjuj klienta Places API.

W takim przypadku możesz użyć klasy CancellationToken. , aby spróbować anulować żądanie dowolnej z klas żądań (na przykład FetchPlaceRequest). Anulowanie subskrypcji odbywa się z możliwie największą dokładnością. Po wysłaniu prośby o anulowanie nie otrzymasz odpowiedzi. Wydanie tokena anulowania NIE gwarantuje, że konkretne żądanie zostanie anulowane. Możesz nadal zostać obciążony opłatą za żądanie, nawet jeśli nie otrzymasz odpowiedzi.

Odpowiedzi na „Autouzupełnianie” (nowe)

Interfejs API zwraca FindAutocompletePredictionsResponsew pliku Task. FindAutocompletePredictionsResponse zawiera listę do pięciu AutocompletePrediction obiektów reprezentujących przewidywane miejsca. Lista może być pusta, jeśli na niej nie ma znane miejsce odpowiadające zapytaniu i kryteriom filtra.

W przypadku każdego przewidywanego miejsca możesz wywołać następujące metody, aby je pobrać szczegóły:

• getFullText(CharacterStyle)zwraca pełny tekst opisu miejsca. To połączenie atrybutów tekst główny i dodatkowy. Przykład: „Wieża Eiffla, aleja Anatole France, Paryż, Francja”. Ta metoda pozwala dodatkowo wyróżnić sekcje pasującego do wyszukiwania i wybranego stylu. Użyj 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. Jest to zazwyczaj nazwa miejsca. Przykłady: „Wieża Eiffla” i „123 Pitt Street”.
• getSecondaryText(CharacterStyle) zwraca tekst opisu miejsca podmiotu zależnego. Jest to przydatne, na przykład jako drugi wiersz podczas wyświetlania przewidywań autouzupełniania. Przykłady: „A Avenue Anatole France, Paris, France” i „Sydney, Nowa Południowa Walia”.
• getPlaceId() zwraca identyfikator 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łnianie, patrz Szczegóły miejsca (Nowość). 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ślać 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 i ustala kolejność wyników na podstawie ich postrzeganej 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. 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 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 jest odrzucana z błędem INVALID_REQUEST, jeśli:

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

  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 określona jako lista maksymalnie 15-znakowych wartości ccTLD („domena najwyższego poziomu”). Jeśli go pominiesz, do odpowiedzi nie będą stosowane żadne ograniczenia. Przykład: aby ograniczyć regiony do Niemiec i Francji:

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

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

• przesunięcie wejścia,

  Odsunięcie znaku Unicode od 0, wskazujące pozycję kursora w zapytaniu. Pozycja kursora może wpływać na wyświetlane podpowiedzi. Jeśli to pole jest puste, domyślnie zostanie ustawiona długość zapytania.

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

• 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 elementy naraz. Ograniczenie lokalizacji to określenie regionu, w którym muszą się znajdować wyniki, a uwzględnienie lokalizacji to określenie regionu, w pobliżu którego muszą się znajdować wyniki. Główna różnica polega na tym, z uprzedzeniami lokalizacji, wyniki spoza określonego regionu mogą nadal być zwracane.

  • Uwzględnianie lokalizacji

    Określa obszar wyszukiwania. Ta lokalizacja działa raczej stronniczo, a nie ogranicza, więc wyniki poza określonym obszarem mogą być nadal zwracane.

    Aby ustawić parametr preferencji lokalizacji, 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 się mieścić w zakresie między 0,0 i 50000,0 włącznie. Wartością domyślną jest 0,0. W przypadku ograniczeń dotyczących lokalizacji: musisz ustawić promień na wartość większą niż 0,0. W przeciwnym razie żądanie zwraca Brak wyników.

  • Prostokąt to widoczny obszar o długości i szerokości szerokości geograficznej, reprezentowany przez dwa elementy. po przekątnej low i high. Widoczny obszar jest uważany za obszar zamknięty, co oznacza, że obejmuje jego 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 błędów zależą od wersji pakietu SDK, której używasz. 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.

    Wartości low 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 ma zostać obliczona bezpośrednia odległość do miejsce docelowe (dostęp przy użyciu: getDistanceMeters()). Jeśli ta wartość to odległość w linii prostej nie zostanie zwrócona. Wartość musi być określona jako współrzędne geograficzne:

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

• Kod regionu

  Kod regionu używany do formatowania odpowiedzi, w tym formatowanie adresu, określony jako ccTLD („domena najwyższego poziomu”) dwuznakową. Większość kodów ccTLD jest identyczna z kodami ISO 3166-1. z kilkoma istotnymi wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (co.uk), natomiast kod ISO 3166-1 to „gb”. (technicznie dla funkcji podmiotu „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 . 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 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 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 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: Tokeny sesji.

Przykłady autouzupełniania (nowe)

Użyj ograniczenia lokalizacji i promowania lokalizacji

Autouzupełnianie (nowość) domyślnie używa promowania ze względu na adres IP do: kontrolować obszar wyszukiwania. W przypadku użycia ukierunkowania na adres IP interfejs API używa adresu IP urządzenia, aby ukierunkować wyniki. Opcjonalnie możesz użyć atrybutu lokalizacja z ograniczeniami lub stronnością lokalizacji, ale nie aby określić obszar wyszukiwania.

Ograniczenie lokalizacji określa obszar wyszukiwania. Wyniki spoza określonego obszaru nie są zwracane. W przykładzie poniżej użyto ograniczenia lokalizacji Żądanie do kołowego ograniczenia lokalizacji z wyśrodkowanym promieniem 5000 m. w 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 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 żą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

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 nazwa zostanie pominięta, zwracane są wszystkie typy.

Poniższy przykład określa ciąg zapytania „Piłka nożna”. i używa podstawowego typ, aby ograniczyć wyniki do instytucji określonego 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ępna 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

Z autouzupełniania (nowego) możesz korzystać nawet bez mapy. Jeśli musisz pokazać mapę 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. Dla: Więcej informacji znajdziesz w sekcji Wyświetlanie logo Google oraz atrybucje.