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