Запрос «Поиск поблизости (новый)» принимает один или несколько типов мест и возвращает список соответствующих мест в указанной области. Требуется маска поля, определяющая один или несколько типов данных. Поиск поблизости (новое) поддерживает только запросы 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.attributions
,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.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.routingSummaries
, *places.servesBeer
,places.servesBreakfast
places.servesCoffee
places.servesBrunch
,places.servesCocktails
,places.servesDessert
,places.servesDinner
,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
чтобы фильтровать результаты по основному типу места.Место также может иметь несколько значений типов из таблицы типов, связанных с ним. Например, ресторан может иметь следующие типы:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. ИспользуйтеincludedTypes
иexcludedTypes
чтобы фильтровать результаты в списке типов, связанных с местом.Когда вы указываете общий основной тип, например
"restaurant"
или"hotel"
, ответ может содержать места с более конкретным основным типом, чем указанный. Например, вы указываете, что необходимо включить основной тип"restaurant"
. Тогда ответ может содержать места с основным типом"restaurant"
, но ответ также может содержать места с более конкретным основным типом, например"chinese_restaurant"
или"seafood_restaurant"
.Если для поиска заданы ограничения нескольких типов, возвращаются только места, удовлетворяющие всем ограничениям. Например, если вы укажете
{"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.