Запрос «Поиск поблизости (новый)» принимает один или несколько типов мест и возвращает список соответствующих мест в указанной области. Требуется маска поля, определяющая один или несколько типов данных. Поиск поблизости (новинка) поддерживает только запросы POST.
API Explorer позволяет вам делать запросы в реальном времени, чтобы вы могли ознакомиться с API и опциями API:
Попробуй это!Попробуйте интерактивную демонстрацию , чтобы увидеть результаты поиска поблизости (новое), отображаемые на карте.
Запросы поиска поблизости (новые)
Запрос «Поиск поблизости (новый)» — это запрос HTTP POST к URL-адресу в форме:
https://places.googleapis.com/v1/places:searchNearby
Передайте все параметры в теле запроса JSON или в заголовках как часть запроса POST. Например:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Поиск поблизости (новые) ответы
Поиск поблизости (новый) возвращает в качестве ответа объект JSON . В ответ:
- Массив
places
содержит все совпадающие места. - Каждое место в массиве представлено объектом
Place
. ОбъектPlace
содержит подробную информацию об одном месте. - FieldMask, переданный в запросе, определяет список полей, возвращаемых в объекте
Place
.
Полный объект JSON имеет вид:
{ "places": [ { object (Place) } ] }
Обязательные параметры
Маска поля
Укажите список полей, которые будут возвращены в ответе, создав маску поля ответа . Передайте маску поля ответа методу, используя параметр URL
$fields
илиfields
или HTTP-заголовокX-Goog-FieldMask
. В ответе нет списка возвращаемых полей по умолчанию. Если вы опустите маску поля, метод вернет ошибку.Маскирование полей — это хорошая практика проектирования, позволяющая избежать запроса ненужных данных, что помогает избежать ненужного времени обработки и затрат на выставление счетов.
Укажите разделенный запятыми список типов данных о местах, которые необходимо вернуть. Например, чтобы получить отображаемое имя и адрес места.
X-Goog-FieldMask: places.displayName,places.formattedAddress
Используйте
*
чтобы получить все поля.X-Goog-FieldMask: *
Укажите одно или несколько из следующих полей:
Следующие поля активируют SKU «Поиск поблизости (базовый)» :
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
* ,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
* Полеplaces.name
содержит имя ресурса места в форме:places/ PLACE_ID
. Используйтеplaces.displayName
для доступа к текстовому названию места.Следующие поля активируют SKU «Поиск поблизости (расширенный)» :
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Следующие поля активируют SKU «Поиск поблизости (предпочтительный)» :
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
places.servesDinner
places.outdoorSeating
,places.reservable
places.restroom
places.reviews
,places.servesBeer
, места.сервыЗавтрак ,places.servesBreakfast
,places.servesBrunch
,places.servesCocktails
,places.servesCoffee
,places.servesDesserts
,places.servesLunch
,places.servesVegetarianFood
,places.servesWine
,places.takeout
МестоположениеОграничение
Область поиска указана в виде круга, определяемого центральной точкой и радиусом в метрах. Радиус должен находиться в диапазоне от 0,0 до 50000,0 включительно. Радиус по умолчанию — 0,0. Вы должны установить его в своем запросе на значение больше 0,0.
Например:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Дополнительные параметры
includeTypes/excludedTypes, includePrimaryTypes/excludedPrimaryTypes
Позволяет указать список типов из таблицы типов A, используемых для фильтрации результатов поиска. В каждой категории ограничения типов можно указать до 50 типов.
Место может иметь только один основной тип из таблицы типов, связанных с ним. Например, основным типом может быть
"mexican_restaurant"
или"steak_house"
. ИспользуйтеincludedPrimaryTypes
иexcludedPrimaryTypes
чтобы фильтровать результаты по основному типу места.Место также может иметь несколько значений типов из таблицы типов A, связанных с ним. Например, ресторан может иметь следующие типы:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. ИспользуйтеincludedTypes
иexcludedTypes
, чтобы фильтровать результаты в списке типов, связанных с местом.Если для поиска заданы ограничения нескольких типов, возвращаются только места, удовлетворяющие всем ограничениям. Например, если вы укажете
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, возвращаемые места предоставляют услуги, связанные с"restaurant"
, но не работают в основном как"steak_house"
.включенные типы
Разделенный запятыми список типов мест из таблицы А для поиска. Если этот параметр опущен, возвращаются места всех типов.
исключенные типы
Список типов мест из таблицы А , разделенных запятыми, которые следует исключить из поиска.
Если вы укажете в запросе как
includedTypes
(например,"school"
), так иexcludedTypes
(например,"primary_school"
), то в ответ будут включены места, которые относятся к категории"school"
, но не к категории"primary_school"
. Ответ включает места, соответствующие хотя бы одному изincludedTypes
и ни одному изexcludedTypes
.Если есть какие-либо конфликтующие типы, например тип, присутствующий как в
includedTypes
, так иexcludedTypes
, возвращается ошибкаINVALID_REQUEST
.включеноPrimaryTypes
Разделенный запятыми список основных типов мест из таблицы А для включения в поиск.
исключенные первичные типы
Разделенный запятыми список основных типов мест из таблицы А , которые необходимо исключить из поиска.
Если есть какие-либо конфликтующие первичные типы, например тип, встречающийся как в
includedPrimaryTypes
, так иexcludedPrimaryTypes
, возвращается ошибкаINVALID_ARGUMENT
.языковой код
Язык, на котором возвращаются результаты.
- См. список поддерживаемых языков . Google часто обновляет поддерживаемые языки, поэтому этот список может быть неполным.
- Если
languageCode
не указан, API по умолчанию имеет значениеen
. Если вы укажете неверный код языка, API вернет ошибкуINVALID_ARGUMENT
. - API делает все возможное, чтобы предоставить почтовый адрес, который будет удобен для чтения как пользователем, так и местными жителями. Для достижения этой цели он возвращает адреса на местном языке, транслитерированные в сценарий, который при необходимости читается пользователем, с учетом предпочтительного языка. Все остальные адреса возвращаются на предпочитаемом языке. Все компоненты адреса возвращаются на одном языке, выбранном из первого компонента.
- Если имя недоступно на предпочитаемом языке, API использует наиболее близкое совпадение.
- Предпочтительный язык оказывает небольшое влияние на набор результатов, которые API выбирает для возврата, и порядок их возврата. Геокодер интерпретирует сокращения по-разному в зависимости от языка, например сокращения типов улиц или синонимы, которые могут быть допустимы для одного языка, но недопустимы для другого.
МаксРезультатКаунт
Указывает максимальное количество возвращаемых результатов по местам. Должно быть от 1 до 20 (по умолчанию) включительно.
рангПредпочтение
Используемый тип рейтинга. Если этот параметр опущен, результаты ранжируются по популярности. Может быть одним из следующих:
-
POPULARITY
(по умолчанию) Сортирует результаты по популярности. -
DISTANCE
Сортирует результаты в порядке возрастания по расстоянию от указанного местоположения.
-
Код региона
Код региона, используемый для форматирования ответа в виде двухсимвольного значения кода CLDR . Нет значения по умолчанию.
Если название страны в поле
formattedAddress
в ответе соответствуетregionCode
, код страны опускается вformattedAddress
. Этот параметр не влияет наadrFormatAddress
, который всегда включает название страны, или наshortFormattedAddress
, который никогда его не включает.Большинство кодов CLDR идентичны кодам ISO 3166-1, за некоторыми заметными исключениями. Например, нДВУ Соединенного Королевства — «uk» (.co.uk), а код ISO 3166-1 — «gb» (технически для организации «Соединенное Королевство Великобритании и Северной Ирландии»). Параметр может повлиять на результаты в соответствии с действующим законодательством.
Примеры поиска поблизости (новые)
Найти места одного типа
В следующем примере показан запрос «Поиск поблизости (новый)» для отображаемых названий всех ресторанов в радиусе 500 метров, определяемых circle
:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Обратите внимание, что заголовок X-Goog-FieldMask
указывает, что ответ содержит следующие поля данных: places.displayName
. Тогда ответ имеет вид:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
Добавьте дополнительные типы данных в маску поля, чтобы вернуть дополнительную информацию. Например, добавьтеplaces.formattedAddress places.formattedAddress,places.types,places.websiteUri
, чтобы включить в ответ адрес, тип и веб-адрес ресторана:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965}, "radius": 500.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
Теперь ответ имеет вид:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
Находите места разных типов
В следующем примере показан запрос «Поиск поблизости (новый)» для отображаемых названий всех магазинов повседневного спроса и винных магазинов в радиусе 1000 метров от указанного circle
:
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearbyВ этом примере к маске поля добавляются
places.primaryType
и places.types
, чтобы ответ включал информацию о типе каждого места, что упрощает выбор подходящего места из результатов.Исключить тип места из поиска
В следующем примере показан запрос «Поиск поблизости (новый)» для всех мест типа "school"
, исключая все места типа "primary_school"
, результаты ранжируются по расстоянию:
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Поиск всех мест рядом с определенной областью, ранжируя их по расстоянию.
В следующем примере показан запрос «Поиск поблизости (новый)» для мест рядом с точкой в центре Сан-Франциско. В этом примере вы включаете параметр rankPreference
для ранжирования результатов по расстоянию:
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Попробуй это!
API Explorer позволяет вам создавать примеры запросов, чтобы вы могли ознакомиться с API и опциями API.
- Выберите значок API,
, в правой части страницы.
- При необходимости разверните Показать стандартные параметры и установите для параметра
fields
маску поля . - При желании отредактируйте тело запроса .
- Нажмите кнопку «Выполнить» . Во всплывающем окне выберите учетную запись, которую вы хотите использовать для отправки запроса.
На панели API Explorer выберите значок развертывания,
, чтобы развернуть окно API Explorer.