Wyszukiwanie w pobliżu (nowość)

Żądanie wyszukiwania w pobliżu (nowe) przyjmuje jako dane wejściowe region, w którym ma się odbyć wyszukiwanie. Jest on określony jako okrąg zdefiniowany przez współrzędne geograficzne środka okręgu oraz promień w metrach. Żądanie zwraca listę pasujących miejsc, z których każde jest reprezentowane przez Place obiekt, w określonym obszarze wyszukiwania.

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

Żądania wyszukiwania w pobliżu (nowe)

Aby wysłać żądanie wyszukiwania w pobliżu (nowe), wywołaj metodę PlacesClient.searchNearby, przekazując obiekt SearchNearbyRequest , który określa parametry żądania.

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

• Lista pól, które mają zostać zwrócone w obiekcie Place, znana też jako maska pola. 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 lokalizacji dla 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 Place w odpowiedzi mają zawierać 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 wyszukiwania w pobliżu (nowe)

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

• Listę obiektów Place, które reprezentują wszystkie pasujące miejsca. Każde pasujące miejsce jest reprezentowane przez 1 obiekt Place.
• Każdy obiekt Place zawiera tylko pola zdefiniowane przez listę pól przekazaną 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 Dostęp do pól danych obiektu Place.

Wymagane parametry

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

• Lista pól

  Gdy prosisz o informacje o miejscu, musisz określić dane, które mają zostać zwrócone w obiekcie Place dla tego miejsca, jako maskę 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 pomaga uniknąć niepotrzebnego czasu przetwarzania i opłat.

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

  • Następujące pola aktywują jednostkę SKU Wyszukiwanie w pobliżu Pro:

    Place.Field.ADDRESS_COMPONENTS
Place.Field.BUSINESS_STATUS
Place.Field.ADDRESS
Place.Field.DISPLAY_NAME >*
    * Użyj zamiast Place.Field.NAME, które jest wycofane.
    Place.Field.ICON_BACKGROUND_COLOR
Place.Field.ICON_MASK_URL*
        * Użyj zamiast Place.Field.ICON_URL, które jest wycofane.
    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

    Pełną listę pól i powiązanych z nimi jednostek SKU znajdziesz w artykule Pola danych o miejscach (nowe).

  • Następujące pola aktywują jednostkę SKU Wyszukiwanie w pobliżu Enterprise:

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

    Pełną listę pól i powiązanych z nimi jednostek SKU znajdziesz w artykule Pola danych o miejscach (nowe).

  • Następujące pola aktywują Wyszukiwanie w pobliżu Enterprise Plus 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

    Pełną listę pól i powiązanych z nimi jednostek SKU znajdziesz w artykule Pola danych o miejscach (nowe).

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

  Ten przykład definiuje listę 2 wartości pól, aby określić, że obiekt Place zwracany przez żądanie ma zawierać pola Place.Field.ID i Place.Field.DISPLAY_NAME fields:

// 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 lokalizacji

  Obiekt LocationRestriction , który określa region, w którym ma się odbyć wyszukiwanie. Jest on zdefiniowany jako okrąg zdefiniowany przez środek 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 określisz zbyt mały promień, odpowiedź będzie zawierać 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

  Pozwala określić listę typów z tabeli A, które mają być używane do filtrowania wyników wyszukiwania. W każdej kategorii ograniczeń typu można określić maksymalnie 50 typów.

  Miejsce może mieć tylko 1 typ podstawowy z tabeli A. Typ podstawowy może być np. "mexican_restaurant" lub "steak_house". Użyj includedPrimaryTypes i excludedPrimaryTypes, aby filtrować wyniki według typu podstawowego miejsca.

  Miejsce może też mieć wiele wartości typu z typó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 według listy typów powiązanych z miejscem.

  Jeśli określisz ogólny typ podstawowy, np. "restaurant" lub "hotel", odpowiedź może zawierać miejsca z bardziej szczegółowym typem podstawowym niż ten, który został określony. Na przykład określisz, że ma być uwzględniony typ podstawowy "restaurant". Odpowiedź może wtedy zawierać miejsca z typem podstawowym "restaurant", ale odpowiedź może też zawierać miejsca z bardziej szczegółowym typem podstawowym, np. "chinese_restaurant" lub "seafood_restaurant".

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

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

  Uwzględnione typy

  Lista typów miejsc z tabeli A, które mają być wyszukiwane. Jeśli ten parametr zostanie pominięty, zwracane są miejsca wszystkich typów.

  Aby ustawić parametr uwzględnionych typów, 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 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 1 z the includedTypes i żadnego z excludedTypes.

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

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

  Wykluczone typy podstawowe

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

  Jeśli występują sprzeczne typy podstawowe, np. typ pojawia się zarówno w includedPrimaryTypes i 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 wyszukiwania miejsc, które mają zostać zwrócone. Wartość musi mieścić się w przedziale od 1 do 20 (domyślnie) włącznie.

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

• Preferencje rankingu

  Typ rankingu do użycia. Jeśli ten parametr zostanie pominięty, wyniki są sortowane według popularności. Może to być jedna 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 określonej lokalizacji.

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

• Kod regionu

  Kod regionu używany do formatowania odpowiedzi, określony jako dwuznakowa wartość kodu 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 FORMATTED_ADDRESS.

  Większość kodów CLDR jest identyczna z kodami ISO 3166-1, z kilkoma istotnymi 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 na podstawie obowiązującego prawa.

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

Wyświetlanie atrybucji w aplikacji

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

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