Wyszukiwanie w pobliżu (nowość)

Żądanie wyszukiwania w pobliżu (nowe) przyjmuje jako dane wejściowe region do wyszukania określony jako okrąg zdefiniowany przez współrzędne geograficzne punktu środkowego okręgu i 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 przefiltrować odpowiedź, podając listę typów miejsc, które mają być wyraźnie uwzględnione w odpowiedzi lub z niej wykluczone. Możesz na przykład określić, że w odpowiedzi mają się znaleźć tylko miejsca typu „restauracja”, „piekarnia” i „kawiarnia”, lub wykluczyć wszystkie miejsca typu „szkoła”.

Żądania wyszukiwania w pobliżu (nowe)

Wyślij żądanie wyszukiwania w pobliżu (nowe), wywołując funkcję PlacesClient.searchNearby i przekazując obiekt SearchNearbyRequest definiujący 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ą pola. Jeśli nie określisz co najmniej jednego pola na liście pól lub pominiesz listę pól, wywołanie zwróci błąd.
• Ograniczenie lokalizacji obszaru wyszukiwania zdefiniowane jako para szerokości i długości geograficznej oraz wartość promienia w metrach.

Ten przykład żądania wyszukiwania w pobliżu określa, że obiekty odpowiedzi Place zawierają pola miejsca Place.Field.ID i Place.Field.DISPLAY_NAME dla każdego obiektu Place w wynikach wyszukiwania. Filtruje też odpowiedź, aby zwracać tylko miejsca typu „restauracja” i „kawiarnia”, ale wykluczać miejsca typu „pizzeria” i „restauracja amerykańska”.

// 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 z wyszukiwania w pobliżu (nowość)

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

• Lista obiektów Place reprezentujących wszystkie pasujące miejsca, przy czym każdy obiekt Place odpowiada jednemu pasującemu miejscu.
• Każdy obiekt Place zawiera tylko pola zdefiniowane na liście pól przekazanej w żądaniu.

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

// 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 nazwę każdego pasującego miejsca. Następnie możesz użyć 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 Uzyskiwanie dostępu do pól danych obiektu Place.

Wymagane parametry

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

• Lista pól

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

  Określ co najmniej jedno z tych pól:

  • Te pola aktywują SKU Nearby Search Pro:

    Place.Field.ADDRESS_COMPONENTS
Place.Field.BUSINESS_STATUS
Place.Field.ADDRESS
Place.Field.DISPLAY_NAME >*
        * Użyj zamiast parametru Place.Field.NAME, który został wycofany.
    Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL*
        * Używaj zamiast wycofanej funkcji Place.Field.ICON_URL.
    Place.Field.ID
Place.Field.LAT_LNG
Place.Field.PHOTO_METADATAS
Place.Field.PLUS_CODE
Place.Field.PRIMARY_TYPE
Place.Field.PRIMARY_TYPE_DISPLAY_NAME
Place.Field.RESOURCE_NAME
Place.Field.TYPES
Place.Field.UTC_OFFSET
Place.Field.VIEWPORT
Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

  • Te pola aktywują Nearby Search Enterprise SKU:

    Place.Field.CURRENT_OPENING_HOURS
Place.Field.CURRENT_SECONDARY_OPENING_HOURS
Place.Field.INTERNATIONAL_PHONE_NUMBER*
        * Używaj zamiast Place.Field.PHONE_NUMBER, które zostało wycofane.
    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*
        * Użyj zamiast Place.Field.USER_RATINGS_TOTAL, które zostało wycofane.
    Place.Field.WEBSITE_URI

  • Te pola aktywują SKU Nearby Search Enterprise Plus:

    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 określić, że obiekt Place zwracany 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 LocationRestriction, który określa region wyszukiwania jako okrąg zdefiniowany przez punkt środkowy i promień w metrach. Promień musi być większy niż 0,0 i mniejszy lub równy 50 000,0. Pamiętaj, że jeśli podasz zbyt mały promień, w odpowiedzi otrzymasz wartość ZERO_RESULTS.

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

Parametry opcjonalne

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

• Typy i typy podstawowe

  Umożliwia określenie listy typów z tabeli A, które będą używane do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń dotyczących typu możesz określić maksymalnie 50 typów.

  Miejsce może mieć tylko jeden typ podstawowy z typów wymienionych w tabeli A. Na przykład typ podstawowy może być "mexican_restaurant" lub "steak_house". Użyj includedPrimaryTypes i excludedPrimaryTypes, aby filtrować wyniki według głównego typu miejsca.

  Miejsce może też mieć wiele wartości typu z typów Tabela A z nim powiązanych. Na przykład restauracja może mieć te typy: "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment". Użyj znaków 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ż podany. Na przykład określasz, że chcesz uwzględnić typ podstawowy "restaurant". Odpowiedź może wtedy zawierać miejsca z podstawowym typem "restaurant", ale może też zawierać miejsca z bardziej szczegółowym typem podstawowym, np. "chinese_restaurant" lub "seafood_restaurant".

  Jeśli wyszukiwanie zawiera 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 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 sekcji Żądania wyszukiwania w pobliżu (nowe).

  Uwzględnione typy

  Lista typów miejsc z tabeli A, których chcesz wyszukać. Jeśli ten parametr zostanie pominięty, zwracane są miejsca wszystkich typów.

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

  Wykluczone typy

  Lista typów miejsc z tabeli A, które mają być wykluczone 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, które są sklasyfikowane jako "school", ale nie jako "primary_school". Odpowiedź zawiera miejsca, które pasują do co najmniej jednego z includedTypes i żadnego z excludedTypes.

  Jeśli wystąpią sprzeczne typy, np. typ pojawiający się zarówno w 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 głównych typów miejsc z tabeli A, które mają być uwzględnione w wyszukiwaniu.

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

  Wykluczone typy podstawowe

  Lista głównych typów miejsc z tabeli A, które mają zostać wykluczone z wyszukiwania.

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

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

• Maksymalna liczba wyników

  Określa maksymalną liczbę wyników dotyczących miejsc do zwrócenia. Musi mieścić się w przedziale od 1 do 20 (wartość domyślna) włącznie.

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

• Preferencje dotyczące rankingu

  Typ rankingu do użycia. Jeśli ten parametr zostanie pominięty, wyniki będą sortowane według popularności. Może mieć jedną z tych wartości:

  • POPULARITY (domyślnie) Sortuje wyniki według popularności.
  • DISTANCE Sortuje wyniki w kolejności rosnącej według odległości od podanej lokalizacji.

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

• Kod regionu

  Kod regionu używany do formatowania odpowiedzi, podany jako dwuznakowy kod CLDR. Nie ma wartości domyślnej.

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

  Większość kodów CLDR jest identyczna z kodami ISO 3166-1, z kilkoma istotnymi wyjątkami. Na przykład krajowa domena najwyższego poziomu Zjednoczonego Królestwa to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Zjednoczone Królestwo Wielkiej Brytanii i Irlandii Północnej”). W zależności od obowiązujących przepisów parametr może wpływać na wyniki.

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

Wyświetlanie atrybucji w aplikacji

Gdy aplikacja wyświetla informacje uzyskane z PlacesClient, np. zdjęcia i opinie, musi też wyświetlać wymagane atrybucje.

Więcej informacji znajdziesz w zasadach dotyczących pakietu SDK Miejsc na Androida.