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

Выберите платформу: Android iOS Веб-служба JavaScript

Запрос «Поиск поблизости (новый)» принимает в качестве входных данных регион для поиска, заданный в виде круга, определяемый координатами широты и долготы центральной точки круга и радиусом в метрах. Запрос возвращает список подходящих мест, каждое из которых представлено объектом 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.getId() и Place.getName() для доступа к этим полям в каждом объекте Place .

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

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

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

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

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

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

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

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

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

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

    Место также может иметь несколько значений типов из таблицы типов, связанных с ним. Например, ресторан может иметь следующие типы: "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 см. в разделе Запросы поиска поблизости (новые) .

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

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

    Чтобы установить параметр включенных типов, вызовите метод 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, за некоторыми заметными исключениями. Например, нДВУ Соединенного Королевства — «uk» (.co.uk), а его код ISO 3166-1 — «gb» (технически для организации «Соединенное Королевство Великобритании и Северной Ирландии»). Параметр может повлиять на результаты в соответствии с действующим законодательством.

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

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

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

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