Wyszukiwanie w pobliżu (nowe)

Wybierz platformę: Android iOS JavaScript Usługa internetowa

W żądaniu wyszukiwania w pobliżu (nowego) jako danych wejściowych należy podać region, w którym należy szukać, określony w postaci okręgu. Wyznaczone są współrzędne szerokości i długości geograficznej punktu środkowego okręgu oraz promień w metrach. Żądanie zwraca listę pasujących miejsc, a każde z nich reprezentowanych przez obiekt Place w określonym obszarze wyszukiwania.

Domyślnie odpowiedź zawiera miejsca dowolnego typu w obszarze wyszukiwania. Opcjonalnie możesz przefiltrować odpowiedź, określając listę typów miejsc, które chcesz wyraźnie uwzględnić w odpowiedzi lub z niej wykluczyć. Możesz np. uwzględnić w odpowiedzi tylko te miejsca, które są typu „restauracja”, „piekarnia” i „kawiarnia”, lub wykluczyć wszystkie miejsca typu „szkoła”.

Żądania wyszukiwania w pobliżu (nowe)

Wyślij nowe żądanie Wyszukiwania w pobliżu (nowe), wywołując metodę 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, nazywana również 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 w przypadku obszaru wyszukiwania określone jako para szerokości i długości geograficznej oraz wartość promienia w metrach.

To przykładowe żądanie wyszukiwania w pobliżu określa, że odpowiedzi obiektów Place zawierają pola miejsc Place.Field.ID i Place.Field.NAME dla każdego obiektu Place w wynikach wyszukiwania. Filtruje też odpowiedź tylko w taki sposób, by zwrócić tylko miejsca typu „restauracja” i „kawiarnia”, ale wykluczyć miejsca typu „pizza_Restaurant” i „american_ światła”.

// 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);

// 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 Wyszukiwanie w pobliżu (nowe)

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

  • Lista obiektów Place reprezentujących wszystkie pasujące miejsca, z 1 obiektem Place na 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 jako: 

// 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 Miejsca.

Wymagane parametry

Za pomocą obiektu SearchNearbyRequest określ wymagane parametry wyszukiwania.

  • Lista pól

    Po wysłaniu prośby o szczegóły miejsca musisz określić dane do zwrócenia w obiekcie Place jako maskę pola. Aby zdefiniować maskę pola, przekaż tablicę wartości z Place.Field do obiektu SearchNearbyRequest. Maskowanie pól to sprawdzona metoda projektowania, dzięki której nie żądasz zbędnych danych. Pozwala to uniknąć niepotrzebnego czasu przetwarzania i opłat.

    Wypełnij co najmniej jedno z tych pól:

    • Te pola aktywują kod SKU Wyszukiwanie w pobliżu (podstawowe):

      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.ID, Place.Field.NAME, Place.Field.TYPES, Place.Field.UTC_OFFSET, Place.Field.VIEWPORT, Place.Field.WHEELCHAIR_ACCESSIBLE_ENTRANCE

    • Te pola aktywują kod SKU Wyszukiwanie w pobliżu (zaawansowane):

      Place.Field.CURRENT_OPENING_HOURS, Place.Field.SECONDARY_OPENING_HOURS, Place.Field.PHONE_NUMBER, Place.Field.PRICE_LEVEL, Place.Field.RATING, Place.Field.OPENING_HOURS, Place.Field.USER_RATINGS_TOTAL, Place.Field.WEBSITE_URI

    • Te pola aktywują kod SKU (preferowany) w pobliżu:

      Place.Field.CURBSIDE_PICKUP, Place.Field.DELIVERY, Place.Field.DINE_IN, Place.Field.EDITORIAL_SUMMARY, Place.Field.RESERVABLE, Place.Field.REVIEWS, Place.Field.SERVES_BEER, Place.Field.SERVES_BREAKFAST, Place.Field.SERVES_BRUNCH, 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, wywołaj metodę setPlaceFields() podczas tworzenia obiektu SearchNearbyRequest.

    Ten przykład zdefiniowano listę 2 wartości pól określających, że obiekt Place zwrócony przez żądanie zawiera pola Place.Field.ID i Place.Field.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.NAME);

  • Ograniczenie dotyczące lokalizacji

    Obiekt LocationRestriction określający obszar do przeszukania, określony w postaci koła, zdefiniowany przez punkt środkowy i promień w metrach. Promień musi być liczbą z zakresu od 0,0 do 50 000,0 lub równą 50 000,0. Pamiętaj, że określenie zbyt małego promienia spowoduje zwrócenie w odpowiedzi ZERO_RESULTS.

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

Parametry opcjonalne

Za pomocą obiektu SearchNearbyRequest określ opcjonalne parametry wyszukiwania.

  • Typy i typy główne

    Umożliwia określenie listy typów z typów Tabela A używanych do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń typu można określić maksymalnie 50 typów.

    Miejsce może mieć tylko jeden typ podstawowy z powiązanych z nim typów Tabela A. Typem głównym może być np. "mexican_restaurant" lub "steak_house". Aby filtrować wyniki według głównego typu miejsca, użyj właściwości includedPrimaryTypes i excludedPrimaryTypes.

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

    Jeśli wyszukiwanie jest określone z ograniczeniami wielu typów, zwracane są tylko miejsca, które spełniają wszystkie warunki. Jeśli na przykład określisz includedTypes = Arrays.asList("restaurant") i excludedPrimaryTypes = Arrays.asList("steak_house"), zwracane miejsca świadczą usługi powiązane z "restaurant", ale nie działają głównie jako "steak_house".

    Przykład użycia funkcji includedTypes i excludedTypes znajdziesz w sekcji Żądania wyszukiwania w pobliżu (nowe).

    Uwzględnione typy

    Lista typów miejsc z tabeli A do wyszukania. Jeśli pominiesz ten parametr, zwracane będą miejsca wszystkich typów.

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

    Wykluczone typy

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

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

    Jeśli występują kolidujące typy, takie jak typ występujący zarówno w polu includedTypes, jak i w excludedTypes, zostanie zwrócony błąd INVALID_REQUEST.

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

    Uwzględnione typy główne

    Lista głównych typów miejsc z tabeli A, które mają zostać uwzględnione w wyszukiwaniu.

    Aby ustawić uwzględniony parametr typów głównych, wywołaj metodę setIncludedPrimaryTypes() podczas tworzenia obiektu SearchNearbyRequest.

    Wykluczone typy główne

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

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

    Aby ustawić wykluczony parametr typu głównego, wywołaj metodę setExcludedPrimaryTypes() podczas tworzenia obiektu SearchNearbyRequest.

  • Maksymalna liczba wyników

    Określa maksymalną liczbę wyników miejsc do zwrócenia. Wartość musi mieścić się w przedziale od 1 do 20 (domyślnie) włącznie.

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

  • Preferencja rankingu

    Typ rankingu, który ma zostać użyty. Jeśli ten parametr zostanie pominięty, wyniki będą uporządkowane według popularności. Możliwe wartości:

    • POPULARITY (domyślnie) sortuje wyniki na podstawie ich popularności.
    • DISTANCE sortuje wyniki w kolejności rosnącej według odległości od określonej lokalizacji.

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

  • Kod regionu

    Kod regionu używany do formatowania odpowiedzi podany jako wartość dwuznakowego kodu CLDR. Nie ma wartości domyślnej.

    Jeśli nazwa kraju w polu formattedAddress w odpowiedzi jest zgodna z nazwą regionCode, kod kraju jest pomijany w polu formattedAddress.

    Większość kodów CLDR jest identyczna z kodami ISO 3166-1 z kilkoma wyjątkami. Na przykład domena ccTLD Wielkiej Brytanii to „uk” (.co.uk), a kod ISO 3166-1 to „gb” (technicznie dla podmiotu „Wielka Brytania i Irlandia Północna”). 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 SearchNearbyRequest.

Wyświetl atrybucję w swojej aplikacji

Gdy aplikacja wyświetla informacje uzyskane z usługi PlacesClient, np. zdjęcia i opinie, musi też wyświetlać wymagane informacje o źródłach.

Więcej informacji znajdziesz w artykule o zasadach korzystania z pakietu SDK Miejsc na Androida.