Запрос «Поиск поблизости (новый)» принимает в качестве входных данных регион для поиска, заданный в виде круга, определяемый координатами широты и долготы центральной точки круга и радиусом в метрах. Запрос возвращает список подходящих мест, каждое из которых представлено объектом Place
, в пределах указанной области поиска.
По умолчанию ответ содержит места всех типов в области поиска. При желании вы можете отфильтровать ответ, указав список типов мест, которые нужно явно включить в ответ или исключить из него. Например, вы можете указать в ответе включать только те места, которые относятся к типу «ресторан», «пекарня» и «кафе», или исключить все места типа «школа».
Запросы поиска поблизости (новые)
Сделайте запрос «Поиск поблизости (новый)», вызвав PlacesClient.searchNearby
и передав объект SearchNearbyRequest
, который определяет параметры запроса.
Объект SearchNearbyRequest
указывает все обязательные и необязательные параметры запроса. К обязательным параметрам относятся:
- Список полей, возвращаемых в объекте
Place
, который также называется маской поля. Если вы не укажете хотя бы одно поле в списке полей или опустите список полей, вызов вернет ошибку. - Ограничение местоположения для области поиска, определяемое как пара широты/долготы и значение радиуса, в метрах.
В этом примере запроса поиска поблизости указывается, что ответные объекты Place
содержат поля места Place.Field.ID
и Place.Field.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.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.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.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
Следующие поля активируют SKU «Поиск поблизости (предпочтительный)» :
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
Чтобы задать параметр списка полей, вызовите метод
setPlaceFields()
при построении объектаSearchNearbyRequest
.В следующем примере определяется список из двух значений полей, чтобы указать, что объект
Place
, возвращаемый запросом, содержит поляPlace.Field.ID
и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);
Ограничение местоположения
Объект
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 . Значения по умолчанию нет.
Если название страны в поле
formattedAddress
в ответе соответствуетregionCode
, код страны вformattedAddress
опускается.Большинство кодов CLDR идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, нДВУ Соединенного Королевства — «uk» (.co.uk), а код ISO 3166-1 — «gb» (технически для организации «Соединенное Королевство Великобритании и Северной Ирландии»). Параметр может повлиять на результаты в соответствии с действующим законодательством.
Чтобы установить параметр кода региона, вызовите метод
setRegionCode()
при построении объектаSearchNearbyRequest
.
Отображение авторства в вашем приложении
Когда ваше приложение отображает информацию, полученную от PlacesClient
, например фотографии и обзоры, оно также должно отображать необходимые сведения об авторстве.
Дополнительную информацию см. в разделе Политики для Places SDK для Android .