Wyszukiwanie w pobliżu (nowe)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

Zapytanie „Wyszukiwanie w pobliżu (nowe)” przyjmuje jako dane wejściowe region wyszukiwania określony jako okrąg zdefiniowany przez współrzędne szerokości i długości geograficznej punktu środkowego oraz promień w metrach. Żądanie zwraca listę pasujących miejsc, z których każde jest reprezentowane przez obiekt Place w określonym obszarze wyszukiwania.

Domyślnie odpowiedź zawiera miejsca wszystkich typów w obszarze wyszukiwania. Opcjonalnie możesz odfiltrować odpowiedź, podając listę typów miejsc, które mają być wyraźnie uwzględnione lub wykluczone z odpowiedzi. Możesz na przykład określić, aby w odpowiedzi uwzględnić tylko miejsca typu „restauracja”, „piekarnia” i „kawiarnia” lub wykluczyć wszystkie miejsca typu „szkoła”.

Wyszukiwanie w pobliżu (nowe)

Prześlij żądanie wyszukiwania w pobliżu (Nowe) przez wywołanie funkcji PlacesClient.searchNearby, przekazując obiekt SearchNearbyRequest, który definiuje parametry żądania.

Obiekt SearchNearbyRequest określa wszystkie wymagane i opcjonalne parametry żądania. Wymagane parametry:

  • Lista pól do zwrócenia w obiekcie Place, który jest też nazywany maską pola. Jeśli na liście pól nie określisz co najmniej 1 pola lub pominiesz listę pól, wywołanie zwróci błąd.
  • Ograniczenie lokalizacji dla obszaru wyszukiwania zdefiniowane jako para szerokości i długości geograficznej oraz wartość promienia w metrach.

W tym przykładzie zapytania o wyszukiwanie w pobliżu określono, że obiekty odpowiedzi Place zawierają pola miejsca Place.Field.ID i Place.Field.DISPLAY_NAME dla każdego obiektu Place w wynikach wyszukiwania. Filtruje ona też odpowiedź, aby zwracać tylko miejsca typu „restaurant” i „cafe”, ale wyklucza miejsca typu „pizza_restaurant” i „american_restaurant”.

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

// Define the search area as a 1000 meter diameter circle in New York, NY.
LatLng center = new LatLng(40.7580, -73.9855);
CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 1000);

// Define a list of types to include.
final List<String> includedTypes = Arrays.asList("restaurant", "cafe");
// Define a list of types to exclude.
final List<String> excludedTypes = Arrays.asList("pizza_restaurant", "american_restaurant");

// Use the builder to create a SearchNearbyRequest object.
final SearchNearbyRequest searchNearbyRequest =
SearchNearbyRequest.builder(/* location restriction = */ circle, placeFields)
    .setIncludedTypes(includedTypes)
    .setExcludedTypes(excludedTypes)
    .setMaxResultCount(10)
    .build());

// Call placesClient.searchNearby() to perform the search.
// Define a response handler to process the returned List of Place objects.
placesClient.searchNearby(searchNearbyRequest)
    .addOnSuccessListener(response -> {
      List<Place> places = response.getPlaces();
    });

Wyszukiwanie w pobliżu (nowy) – odpowiedzi

Klasa SearchNearbyResponse reprezentuje odpowiedź na żądanie wyszukiwania. Obiekt SearchNearbyResponse zawiera:

  • Lista obiektów Place, które reprezentują wszystkie pasujące miejsca, z jednym obiektem Place na każde pasujące miejsce.
  • Każdy obiekt Place zawiera tylko pola zdefiniowane przez listę pól przekazaną w żądaniu.

Na przykład w żądaniu zdefiniowano listę pól: 

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

Ta lista pól oznacza, że każdy obiekt Place w odpowiedzi zawiera tylko identyfikator miejsca i jego nazwę. Następnie możesz używać metod Place.getId() i Place.getName(), aby uzyskać dostęp do tych pól w każdym obiekcie Place.

Więcej przykładów uzyskiwania dostępu do danych w obiekcie Place znajdziesz w artykule Dostęp do pól danych obiektu Miejsce.

Wymagane parametry

Aby określić parametry wymagane do wyszukiwania, użyj obiektu SearchNearbyRequest.

  • Lista pól

    Gdy żądasz szczegółów miejsca, musisz określić dane, które mają zostać zwrócone w obiekcie Place dla tego miejsca jako maski pola. Aby zdefiniować maskę pola, prześlij tablicę wartości z Place.Field do obiektu SearchNearbyRequest. Maskowanie pól to dobra praktyka projektowania, która pozwala uniknąć żądania niepotrzebnych danych, co pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat.

    Podaj co najmniej 1 z tych pól:

    • Te pola powodują wyświetlenie wyszukiwania w pobliżu (podstawowego):

      Place.Field.ADDRESS_COMPONENTS, Place.Field.BUSINESS_STATUS, Place.Field.ADDRESS, Place.Field.ICON_BACKGROUND_COLOR, Place.Field.ICON_URL, Place.Field.LAT_LNG, Place.Field.PHOTO_METADATAS, Place.Field.PLUS_CODE, Place.Field.PRIMARY_TYPE, Place.Field.PRIMARY_TYPE_DISPLAY_NAME, Place.Field.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • Te pola powodują, że wyszukiwanie w pobliżu (zaawansowane) jest dostępne w ramach SKU:

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.CURRENT_SECONDARY_OPENING_HOURS, Place.Field.INTERNATIONAL_PHONE_NUMBER, Place.Field.NATIONAL_PHONE_NUMBER, Place.Field.OPENING_HOURS, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.USER_RATING_COUNT, Place.Field.WEBSITE_URI

    • Te pola powodują wyświetlenie wyszukiwania w pobliżu (preferowane) SKU:

      Place.Field.ALLOWS_DOGS, Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.EV_CHARGE_OPTIONS, Place.Field.FUEL_OPTIONS, Place.Field.GOOD_FOR_CHILDREN, Place.Field.GOOD_FOR_GROUPS, Place.Field.GOOD_FOR_WATCHING_SPORTS, Place.Field.LIVE_MUSIC, Place.Field.MENU_FOR_CHILDREN, Place.Field.OUTDOOR_SEATING, Place.Field.PARKING_OPTIONS, Place.Field.PAYMENT_OPTIONS, Place.Field.RESERVABLE, Place.Field.RESTROOM, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, Place.Field.SERVES_COCKTAILS, Place.Field.SERVES_COFFEE, Place.Field.SERVES_DESSERT, Place.Field.SERVES_DINNER, Place.Field.SERVES_LUNCH, Place.Field.SERVES_VEGETARIAN_FOOD, Place.Field.SERVES_WINE, Place.Field.TAKEOUT

    Aby ustawić parametr listy pól, podczas tworzenia obiektu SearchNearbyRequest wywołaj metodę setPlaceFields().

    W tym przykładzie zdefiniowano listę 2 wartości pól, aby wskazać, że obiekt Place zwrócony przez żądanie zawiera pola Place.Field.ID i Place.Field.DISPLAY_NAME:

// Define a list of fields to include in the response for each returned place.
final List<Place.Field> placeFields = Arrays.asList(Place.Field.ID, Place.Field.DISPLAY_NAME);

  • Ograniczenie dotyczące lokalizacji

    Obiekt LocationRestrictionokreślający region do przeszukania określony jako okrąg z punktami środkowymi i promieniem w metrach. Promień musi być większy niż 0,0 i nie większy niż 50000,0. Pamiętaj, że podanie zbyt małego promienia spowoduje zwrócenie wartości ZERO_RESULTS.

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

Parametry opcjonalne

Aby określić opcjonalne parametry wyszukiwania, użyj obiektu SearchNearbyRequest.

  • Typy i typy główne

    Umożliwia określenie listy typów z tabeli Tabela A, która służy do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń typu możesz określić maksymalnie 50 typów.

    Miejsce może mieć tylko jeden podstawowy typ z typów podanych w tabeli A powiązanych z tym miejscem. Na przykład typ podstawowy może być "mexican_restaurant" lub "steak_house". Użyj właściwości includedPrimaryTypes i excludedPrimaryTypes, aby filtrować wyniki według głównego typu miejsca.

    Miejsce może też mieć wiele wartości typu z typów wymienionych w tabeli A. Na przykład restauracja może mieć te typy: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Użyj includedTypes i excludedTypes, aby filtrować wyniki na liście typów powiązanych z miejscem.

    Jeśli określisz ogólny typ podstawowy, np. "restaurant" lub "hotel", odpowiedź może zawierać miejsca o bardziej szczegółowym typie podstawowym niż określony. Możesz na przykład określić, aby uwzględnić główny typ "restaurant". Odpowiedź może zawierać miejsca o podstawowym typie "restaurant", ale może też zawierać miejsca o bardziej szczegółowym typie podstawowym, takim jak "chinese_restaurant" lub "seafood_restaurant".

    Jeśli wyszukiwanie jest określone z wieloma ograniczeniami typu, zwracane są tylko miejsca, które spełniają wszystkie ograniczenia. Jeśli na przykład podasz wartości includedTypes = Arrays.asList("restaurant") i excludedPrimaryTypes = Arrays.asList("steak_house"), zwrócone miejsca będą oferować usługi związane z "restaurant", ale nie będą działać głównie jako "steak_house".

    Przykład użycia parametrów includedTypes i excludedTypes znajdziesz w artykule Przeglądanie w pobliżu (nowa funkcja) – żądania.

    Uwzględnione typy

    Lista typów miejsc z tabeli A, których szukasz. Jeśli ten parametr zostanie pominięty, zwrócone zostaną miejsca wszystkich typów.

    Aby ustawić parametr included_types, wywołaj metodę setIncludedTypes() podczas tworzenia obiektu SearchNearbyRequest.

    Wykluczone typy

    Lista typów miejsc z tabeli A do wykluczenia z wyszukiwania.

    Jeśli w żądaniu podasz zarówno parametr includedTypes (np. "school"), jak i excludedTypes (np. "primary_school"), odpowiedź będzie zawierać miejsca zakwalifikowane jako "school", ale nie "primary_school". Odpowiedź zawiera miejsca, które pasują do co najmniej jednego z includedTypes i żadnego z excludedTypes.

    Jeśli występują jakieś sprzeczne typy, np. typ występujący zarówno w opcji includedTypes, jak i excludedTypes, zwracany jest błąd INVALID_REQUEST.

    Aby ustawić parametr wykluczonych typów, podczas tworzenia obiektu SearchNearbyRequest wywołaj metodę setExcludedTypes().

    Uwzględnione typy podstawowe

    Lista podstawowych typów miejsc z tabeli A do uwzględnienia w wyszukiwaniu.

    Aby ustawić parametr included_primary_types, wywołaj metodę setIncludedPrimaryTypes() podczas tworzenia obiektu SearchNearbyRequest.

    Wykluczone typy podstawowe

    Lista głównych typów miejsc z tabeli A do wykluczenia z wyszukiwania.

    Jeśli występują jakieś sprzeczne typy podstawowe, np. typ występujący zarówno w includedPrimaryTypes, jak i excludedPrimaryTypes, zwracany jest błąd INVALID_ARGUMENT.

    Aby ustawić parametr wykluczonych typów podstawowych, wywołaj metodę setExcludedPrimaryTypes() podczas tworzenia obiektu SearchNearbyRequest.

  • Maksymalna liczba wyników

    Określa maksymalną liczbę wyników wyszukiwania miejsc do zwrócenia. Musi mieścić się w zakresie od 1 do 20 (domyślnie).

    Aby ustawić parametr maksymalnej liczby wyników, podczas tworzenia obiektu SearchNearbyRequest wywołaj metodę setMaxResultCount().

  • Ustawienie „Ranking”

    Typ używanego rankingu. Jeśli ten parametr zostanie pominięty, wyniki zostaną posortowane według popularności. Może być jedną z tych wartości:

    • POPULARITY (ustawienie domyślne) – sortuje wyniki według ich popularności.
    • DISTANCE Sortuje wyniki w kolejności rosnącej według odległości od wybranej lokalizacji.

    Aby ustawić parametr preferencji rankingu, podczas tworzenia obiektu SearchNearbyRequest wywołaj metodę setRankPreference().

  • Kod regionu

    Kod regionu użyty do sformatowania odpowiedzi, podany jako 2-znakowy kod CLDR. Nie ma wartości domyślnej.

    Jeśli nazwa kraju w polu FORMATTED_ADDRESS w odpowiedzi pasuje do wartości w polu regionCode, kod kraju jest pomijany w polu FORMATTED_ADDRESS.

    Większość kodów CLDR jest identyczna z kodami ISO 3166-1, z niektórymi 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”). 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 SearchNearbyRequest wywołaj metodę setRegionCode().

Wyświetlanie atrybucji w aplikacji

Jeśli aplikacja wyświetla informacje uzyskane z PlacesClient, takie jak zdjęcia i opinie, musi też wyświetlać wymagane informacje o źródłach.

Więcej informacji znajdziesz w artykule Zasady dotyczące pakietu SDK Miejsc na Androida.