Wyszukiwanie w pobliżu (nowość)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

W prośbie o wyszukiwanie w pobliżu (nowa) jako dane wejściowe podajesz region wyszukiwania określony jako okrąg zdefiniowany przez współrzędne geograficzne punktu środkowego i promień w metrach. W odpowiedzi na tę prośbę zwraca ona 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”.

żądania wyszukiwania 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 to:

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

W tym przykładowym żądaniu wyszukiwania 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 odpowiedź tak, 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();
    });

odpowiedzi „Szukaj w pobliżu” (nowa wersja);

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 obiektu Place znajdziesz w artykule Dostęp do pól danych obiektu Miejsce.

Wymagane parametry

Użyj obiektu SearchNearbyRequest, aby określić parametry wymagane do wyszukiwania.

  • Lista pól

    Gdy żądasz szczegółów miejsca, musisz określić dane, które mają zostać zwrócone w obiekcie Place miejsca jako maska 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ąć przesyłania niepotrzebnych danych, co z kolei pozwala 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) SKU:

      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ą wyświetlenie wyszukiwania w pobliżu (zaawansowanego) 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świetlanie 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 wyszukiwania określony jako okrąg zdefiniowany przez punkt środkowy i promień w metrach. Promień musi być większy od 0,0 i nie może być 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 podstawowe

    Umożliwia określenie listy typów z tabeli A, które służą do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń typu możesz podać 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ć określony jako "mexican_restaurant" lub "steak_house". Aby filtrować wyniki według głównego typu miejsca, użyj opcji includedPrimaryTypes i excludedPrimaryTypes.

    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 pól includedTypes i excludedTypes, aby odfiltrować wyniki na liście typów powiązanych z danym 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ż ten, który został podany. Możesz na przykład określić, że chcesz uwzględnić podstawowy typ "restaurant". Odpowiedź może zawierać miejsca o głównym typie "restaurant", ale może też zawierać miejsca o bardziej szczegółowym typie głównym, takim jak "chinese_restaurant" lub "seafood_restaurant".

    Jeśli w wyszukiwaniu określono wiele ograniczeń typu, zwracane są tylko miejsca, które spełniają wszystkie te ograniczenia. Jeśli na przykład określisz includedTypes = Arrays.asList("restaurant") i excludedPrimaryTypes = Arrays.asList("steak_house"), zwrócone miejsca oferują usługi związane z "restaurant", ale nie działają głównie jako "steak_house".

    Przykład użycia funkcji includedTypes i excludedTypes znajdziesz w sekcji Prośby o wyszukiwanie w pobliżu (nowa).

    Uwzględnione typy

    Lista typów miejsc z tabeli A, których można szukać. Jeśli pominiesz ten parametr, zwrócone zostaną miejsca wszystkich typów.

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

    Wykluczone typy

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

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

    Jeśli występują sprzeczne typy, np. typ występujący zarówno w parametri includedTypes 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 głównych 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 podstawowych 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 głównych, podczas tworzenia obiektu SearchNearbyRequest wywołaj metodę setExcludedPrimaryTypes().

  • 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 rankingu do użycia. Jeśli ten parametr zostanie pominięty, wyniki zostaną posortowane według popularności. Może być jedną z tych wartości:

    • POPULARITY (domyślnie) – 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 informacji o pochodzeniu danych 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 zasadach dotyczących pakietu Places SDK na Androida.