Поиск поблизости (новинка)

Выберите платформу: Android iOS JavaScript Web Service

Разработчики Европейской экономической зоны (ЕЭЗ)

Запрос «Поиск поблизости (новый)» принимает в качестве входных данных область поиска, заданную в виде круга, определяемого координатами широты и долготы центра круга, а также радиусом в метрах. Запрос возвращает список соответствующих мест, каждое из которых представлено объектом Place , в пределах указанной области поиска.

По умолчанию ответ содержит места всех типов в области поиска. Вы можете отфильтровать ответ, указав список типов мест, которые следует явно включить или исключить из ответа. Например, можно включить в ответ только места типа «ресторан», «пекарня» и «кафе» или исключить все места типа «школа».

Запросы поиска поблизости (новые)

Сделайте запрос на поиск поблизости (новый), вызвав PlacesClient.searchNearby и передав объект SearchNearbyRequest , который определяет параметры запроса.

Объект SearchNearbyRequest определяет все обязательные и необязательные параметры запроса. Обязательные параметры включают:

  • Список полей, возвращаемых в объекте Place , также известный как маска полей. Если в списке полей не указано хотя бы одно поле или список полей пропущен, вызов вернёт ошибку.
  • Ограничение местоположения для области поиска, определяемое парой широты/долготы и значением радиуса в метрах.

В этом примере запроса на поиск объектов поблизости указано, что объекты Place содержат поля Place.Field.ID и Place.Field.DISPLAY_NAME для каждого объекта Place в результатах поиска. Он также фильтрует ответ, возвращая только места типа «ресторан» и «кафе», но исключая места типа «пицца_ресторан» и «американский_ресторан».

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

Ответы поиска поблизости (новые)

Класс SearchNearbyResponse представляет ответ на поисковый запрос. Объект SearchNearbyResponse содержит:

  • Список объектов Place , представляющих все соответствующие места, по одному объекту Place на каждое соответствующее место.
  • Каждый объект Place содержит только поля, определенные списком полей, переданным в запросе.

Например, в запросе вы определили список полей как:

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

Этот список полей означает, что каждый объект Place в ответе содержит только идентификатор и название каждого совпадающего места. Для доступа к этим полям в каждом объекте Place можно использовать методы Place.getId() и Place.getName() .

Дополнительные примеры доступа к данным в объекте Place см. в разделе Доступ к полям данных объекта Place .

Обязательные параметры

Используйте объект SearchNearbyRequest , чтобы указать необходимые параметры поиска.

  • Список полей

    При запросе информации о месте необходимо указать возвращаемые данные в объекте Place для этого места в виде маски поля. Чтобы определить маску поля, передайте массив значений из Place.Field в объект SearchNearbyRequest . Маскирование полей — это хорошая практика проектирования, позволяющая избежать запроса ненужных данных, что помогает избежать ненужного времени обработки и дополнительных расходов.

    Укажите одно или несколько из следующих полей:

    • Следующие поля активируют Nearby Search Pro SKU :

      Place.Field.ADDRESS_COMPONENTS
      Place.Field.BUSINESS_STATUS
      Place.Field.ADDRESS
      Place.Field.DISPLAY_NAME >*
      * Используйте вместо Place.Field.NAME , который устарел.
      Place.Field.ICON_BACKGROUND_COLOR
      Place.Field.ICON_MASK_URL *
      * Используйте вместо 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

    • Следующие поля активируют Nearby Search Enterprise SKU :

      Place.Field.CURRENT_OPENING_HOURS
      Place.Field.CURRENT_SECONDARY_OPENING_HOURS
      Place.Field.INTERNATIONAL_PHONE_NUMBER *
      * Используйте вместо Place.Field.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.USER_RATINGS_TOTAL , который устарел.
      Place.Field.WEBSITE_URI

    • Следующие поля активируют Nearby Search 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

    Чтобы задать параметр списка полей, вызовите метод setPlaceFields() при построении объекта SearchNearbyRequest .

    В следующем примере определяется список из двух значений полей, указывающий, что объект Place , возвращаемый запросом, содержит поля Place.Field.ID и 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);

  • Ограничение местоположения

    Объект LocationRestriction , определяющий область поиска, заданную как круг, заданный центральной точкой и радиусом в метрах. Радиус должен быть в диапазоне от 0,0 до 50000,0. При указании слишком маленького радиуса будет возвращен ответ ZERO_RESULTS .

    Чтобы задать параметр ограничения местоположения, вызовите метод setLocationRestriction() при создании объекта SearchNearbyRequest .

Необязательные параметры

Используйте объект SearchNearbyRequest , чтобы указать необязательные параметры поиска.

  • Типы и основные типы

    Позволяет указать список типов из таблицы A, используемых для фильтрации результатов поиска. В каждой категории ограничений типов можно указать до 50 типов.

    Место может иметь только один основной тип из списка типов, связанных с ним в таблице A. Например, основным типом может быть "mexican_restaurant" или "steak_house" . Используйте includedPrimaryTypes и excludedPrimaryTypes для фильтрации результатов по основному типу места.

    Место также может иметь несколько значений типа из таблицы A , связанных с ним. Например, ресторан может иметь следующие типы: "seafood_restaurant" , "restaurant" , "food" , "point_of_interest" , "establishment" . Используйте includedTypes и excludedTypes для фильтрации результатов по списку типов, связанных с местом.

    При указании общего основного типа, например, "restaurant" или "hotel" , ответ может содержать места с более конкретным основным типом, чем указанный. Например, вы указываете, что нужно включить основной тип "restaurant" . В таком случае ответ может содержать места с основным типом "restaurant" , но ответ также может содержать места с более конкретным основным типом, например, "chinese_restaurant" или "seafood_restaurant" .

    Если поиск задан с несколькими ограничениями по типу, будут возвращены только места, удовлетворяющие всем этим ограничениям. Например, если указать includedTypes = Arrays.asList("restaurant") и excludedPrimaryTypes = Arrays.asList("steak_house") , возвращаемые места предоставляют услуги, связанные с "restaurant" но не являются в первую очередь "steak_house" .

    Пример использования includedTypes и excludedTypes смотрите в разделе Запросы Nearby Search (New) .

    Включенные типы

    Список типов мест из таблицы A для поиска. Если этот параметр пропущен, возвращаются места всех типов.

    Чтобы задать параметр включенных типов, вызовите метод setIncludedTypes() при построении объекта SearchNearbyRequest .

    Исключенные типы

    Список типов мест из таблицы А , которые следует исключить из поиска.

    Если в запросе указаны как includedTypes (например, "school" ), так и excludedTypes типы (например, "primary_school" ), то ответ будет включать места, относящиеся к категории "school" , но не "primary_school" . В ответ будут включены места, соответствующие хотя бы одному из includedTypes типов и ни одному из excludedTypes .

    Если имеются конфликтующие типы, например, тип присутствует и в includedTypes , и excludedTypes , возвращается ошибка INVALID_REQUEST .

    Чтобы задать параметр исключенных типов, вызовите метод setExcludedTypes() при построении объекта SearchNearbyRequest .

    Включены основные типы

    Список основных типов мест из Таблицы А для включения в поиск.

    Чтобы задать параметр включенных первичных типов, вызовите метод setIncludedPrimaryTypes() при построении объекта SearchNearbyRequest .

    Исключенные основные типы

    Список основных типов мест из таблицы А для исключения из поиска.

    Если имеются конфликтующие первичные типы, например, тип, присутствующий как в includedPrimaryTypes , так и excludedPrimaryTypes , возвращается ошибка INVALID_ARGUMENT .

    Чтобы задать параметр исключенных первичных типов, вызовите метод setExcludedPrimaryTypes() при построении объекта SearchNearbyRequest .

  • Максимальное количество результатов

    Указывает максимальное количество возвращаемых результатов поиска по месту. Должно быть от 1 до 20 (по умолчанию) включительно.

    Чтобы задать максимальный параметр количества результатов, вызовите метод setMaxResultCount() при создании объекта SearchNearbyRequest .

  • Предпочтение по рангу

    Тип используемого ранжирования. Если этот параметр пропущен, результаты сортируются по популярности. Может быть одним из следующих:

    • POPULARITY (по умолчанию) Сортирует результаты по их популярности.
    • DISTANCE Сортирует результаты в порядке возрастания расстояния от указанного местоположения.

    Чтобы задать параметр предпочтения ранга, вызовите метод setRankPreference() при создании объекта SearchNearbyRequest .

  • Код региона

    Код региона, используемый для форматирования ответа, указывается как двухсимвольное значение кода CLDR . Значение по умолчанию отсутствует.

    Если название страны в поле FORMATTED_ADDRESS в ответе совпадает с regionCode , код страны исключается из FORMATTED_ADDRESS .

    Большинство кодов CLDR идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, ccTLD Великобритании — «uk» (.co.uk), а код ISO 3166-1 — «gb» (технически обозначает «Соединённое Королевство Великобритании и Северной Ирландии»). Этот параметр может влиять на результаты в зависимости от применимого законодательства.

    Чтобы задать параметр кода региона, вызовите метод setRegionCode() при создании объекта SearchNearbyRequest .

Отображение атрибуции в вашем приложении

Когда ваше приложение отображает информацию, полученную от PlacesClient , например фотографии и отзывы, приложение также должно отображать требуемые атрибуции.

Более подробную информацию см. в разделе Политики для Places SDK для Android .