Введение
Получив идентификатор места, вы можете запросить дополнительные сведения о конкретном заведении или объекте инфраструктуры, отправив запрос Place Details (New). Запрос "Сведения о месте (новая версия)" возвращает более полную информацию об указанном месте, например полный адрес, номер телефона, оценки и отзывы пользователей.
Получить идентификатор места можно разными способами. Вы можете использовать:
- Новая версия текстового поиска или новая версия поиска поблизости
- Geocoding API
- Routes API
- Address Validation API
- Автозаполнение (новая версия)
API Explorer позволяет отправлять запросы в реальном времени, чтобы вы могли ознакомиться с API и его возможностями:
Запросы информации о местах (New)
Запрос Place Details (New) – это HTTP-запрос GET в следующем формате:
https://places.googleapis.com/v1/places/PLACE_ID
Передавайте все параметры в виде параметров URL или в заголовках в составе GET-запроса. Пример:
https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?fields=id,displayName&key=API_KEYили в команде curl:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
Ответы на запросы информации о местах (New)
Сервис "Информация о местах" (Новый) возвращает объект JSON в качестве ответа. В ответе:
- Ответ представлен объектом
Place. ОбъектPlaceсодержит подробную информацию о месте. - FieldMask, переданная в запросе, определяет список полей, возвращаемых в объекте
Place.
Полный объект JSON имеет следующий вид:
{ "name": "places/ChIJkR8FdQNB0VQRm64T_lv1g1g", "id": "ChIJkR8FdQNB0VQRm64T_lv1g1g", "displayName": { "text": "Trinidad" } ... }
Обязательные параметры
-
FieldMask
Укажите список полей, которые должны возвращаться в ответе, создав маску полей ответа. Передайте маску поля ответа методу, используя параметр URL
$fieldsилиfieldsлибо заголовок HTTPX-Goog-FieldMask. В ответе нет списка возвращаемых полей по умолчанию. Если вы не укажете маску поля, метод вернет ошибку.Маски полей помогут вам не запрашивать ненужные данные и тем самым сократить время обработки и снизить расходы.
Укажите список типов данных о местах, которые нужно возвращать, разделяя их запятыми. Например, чтобы получить отображаемое название и адрес места.
X-Goog-FieldMask: displayName,formattedAddress
Чтобы получить все поля, используйте
*.X-Goog-FieldMask: *
Укажите одно или несколько из следующих полей:
Следующие поля активируют код Place Details Essentials IDs Only:
attributions
consumerAlert
id
movedPlace
movedPlaceId
name*
photos
*Поле
nameсодержит название ресурса места в видеplaces/PLACE_ID. Чтобы получить текстовое название места, запросите полеdisplayNameв Pro SKU.Полный список полей и связанных с ними кодов приведен в разделе Поля данных о местах (новая версия).
Следующие поля активируют SKU "Информация о местах. Essentials":
addressComponents
addressDescriptor*
adrFormatAddress
formattedAddress
location
plusCode
postalAddress
shortFormattedAddress
types
viewport
* Дескрипторы адресов доступны клиентам в Индии и являются экспериментальной функцией в других странах.
Полный список полей и связанных с ними кодов приведен в разделе Поля данных о местах (новая версия).
Следующие поля активируют код Place Details Pro:
accessibilityOptions
businessStatus
containingPlaces
displayName
googleMapsLinks
googleMapsTypeLabel
googleMapsUri
iconBackgroundColor
iconMaskBaseUri
openingDate
primaryType
primaryTypeDisplayName
pureServiceAreaBusiness
subDestinations
timeZone
utcOffsetMinutes
Полный список полей и связанных с ними кодов приведен в разделе Поля данных о местах (новая версия).
Следующие поля активируют корпоративный код "Сведения о местах":
currentOpeningHours
currentSecondaryOpeningHours
internationalPhoneNumber
nationalPhoneNumber
priceLevel
priceRange
rating
regularOpeningHours
regularSecondaryOpeningHours
transitStation
userRatingCount
websiteUriПолный список полей и связанных с ними кодов приведен в разделе Поля данных о местах (новая версия).
Следующие поля активируют код Place Details Enterprise + Atmosphere:
allowsDogs
curbsidePickup
delivery
dineIn
editorialSummary
evChargeAmenitySummary
evChargeOptions
fuelOptions
generativeSummary
goodForChildren
goodForGroups
goodForWatchingSports
liveMusic
menuForChildren
neighborhoodSummary
parkingOptions
paymentOptions
outdoorSeating
reservable
restroom
reviews
reviewSummary
routingSummaries*
servesBeer
servesBreakfast
servesBrunch
servesCocktails
servesCoffee
servesDessert
servesDinner
servesLunch
servesVegetarianFood
servesWine
takeout
* Только для текстового поиска и поиска поблизости.Полный список полей и связанных с ними кодов приведен в разделе Поля данных о местах (новая версия).
-
placeId
Уникальный текстовый идентификатор места, возвращаемый функцией нового текстового поиска или нового поиска поблизости. Подробнее об идентификаторах мест…
Строка
places/PLACE_IDтакже называется названием ресурса места. В ответе на запрос информации о местах (New), поиска поблизости (New) или текстового поиска (New) эта строка содержится в полеname. Отдельный идентификатор места содержится в полеidответа.
Необязательные параметры
languageCode
Язык, на котором будут возвращены результаты.
- Вы можете ознакомиться со списком поддерживаемых языков. Google часто обновляет список поддерживаемых языков, поэтому он может быть неполным.
-
Если значение
languageCodeне указано, API по умолчанию использует значениеen. Если вы укажете недопустимый код языка, API вернет ошибкуINVALID_ARGUMENT. - API старается предоставить почтовый адрес, который будет понятен как пользователю, так и местным жителям. Для этого он возвращает адреса улиц на местном языке, при необходимости транслитерируя их в шрифт, который может прочитать пользователь, с учетом предпочитаемого языка. Все остальные адреса возвращаются на предпочитаемом языке. Все компоненты адреса возвращаются на одном языке, который выбирается на основе первого компонента.
- Если название на предпочитаемом языке недоступно, API использует ближайшее соответствие.
- Предпочтительный язык незначительно влияет на набор результатов, возвращаемых API, и порядок их следования. Геокодер интерпретирует сокращения по-разному в зависимости от языка. Это касается, например, сокращений для типов улиц или синонимов, которые могут быть допустимы в одном языке, но не в другом.
regionCode
Код региона, используемый для форматирования ответа, в виде двухсимвольного кода CLDR. Значение по умолчанию отсутствует.
Если название страны в поле
formattedAddressответа совпадает сregionCode, код страны удаляется изformattedAddress. Этот параметр не влияет наadrFormatAddress, который всегда включает название страны, или наshortFormattedAddress, который никогда его не включает.Большинство кодов CLDR совпадают с кодами ISO 3166-1, однако имеются некоторые исключения. Например, ccTLD Великобритании – uk (.co.uk), а код ISO 3166-1 – gb (технически для Соединенного Королевства Великобритании и Северной Ирландии). Параметр может влиять на результаты в соответствии с действующим законодательством.
-
sessionToken
Токены сеансов – это создаваемые пользователем строки, которые отслеживают вызовы Autocomplete (New) как "сеансы". В новом методе автозаполнения используются токены сеансов, чтобы сгруппировать этапы запроса и выбора места выполняемого пользователем поиска с функцией автозаполнения в отдельный сеанс для выставления счетов. Токены сеансов передаются в вызовы информации о местах (New), которые следуют за вызовами Autocomplete (New). Подробнее о токенах сеансов…
Пример запроса информации о местах (New)
В примере ниже запрашивается информация о месте по его идентификатору placeId.
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
Обратите внимание, что заголовок X-Goog-FieldMask указывает, что ответ содержит следующие поля данных: id,displayName.
Ответ будет иметь следующий вид:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "displayName": { "text": "Googleplex", "languageCode": "en" } }
Чтобы получить дополнительные сведения, добавьте в маску поля больше типов данных.
Например, добавьте formattedAddress,plusCode, чтобы включить адрес и код Plus Code в ответ:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,formattedAddress,plusCode" \ https://places.googleapis.com/v1/places/ChIJj61dQgK6j4AR4GeTYWZsKWw
Теперь ответ выглядит так:
{ "id": "ChIJj61dQgK6j4AR4GeTYWZsKWw", "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "plusCode": { "globalCode": "849VCWC7+RW", "compoundCode": "CWC7+RW Mountain View, CA, USA" }, "displayName": { "text": "Googleplex", "languageCode": "en" } }
Как получить дескрипторы адресов
Дескрипторы адресов содержат информацию о местоположении объекта, в том числе о ближайших ориентирах и областях, в которых он находится.
В примере ниже показан запрос "информация о местах (новая версия)" для универмага в торговом центре в Сан-Хосе. В этом примере в маску поля включен параметр addressDescriptors:
curl -X GET https://places.googleapis.com/v1/places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4 \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: name,displayName,addressDescriptor"
Ответ содержит место, указанное в запросе, список ближайших ориентиров и расстояние до них, а также список областей и их отношение к месту:
{ "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4", "displayName": { "text": "Macy's", "languageCode": "en" }, "addressDescriptor": { "landmarks": [ { "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "food", "movie_theater", "point_of_interest", "restaurant", "shoe_store", "shopping_mall", "store" ], "spatialRelationship": "WITHIN", "straightLineDistanceMeters": 220.29175 }, { "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4", "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4", "displayName": { "text": "Nordstrom", "languageCode": "en" }, "types": [ "clothing_store", "department_store", "establishment", "point_of_interest", "shoe_store", "store" ], "straightLineDistanceMeters": 329.45178 }, { "name": "places/ChIJmx1c5x7Lj4ARJXJy_CU_JbE", "placeId": "ChIJmx1c5x7Lj4ARJXJy_CU_JbE", "displayName": { "text": "Monroe Parking Garage", "languageCode": "en" }, "types": [ "establishment", "parking", "point_of_interest" ], "straightLineDistanceMeters": 227.05153 }, { "name": "places/ChIJxcwBziHLj4ARUQLAvtzkRCM", "placeId": "ChIJxcwBziHLj4ARUQLAvtzkRCM", "displayName": { "text": "Studios Inn by Daiwa Living California Inc.", "languageCode": "en" }, "types": [ "establishment", "lodging", "point_of_interest", "real_estate_agency" ], "straightLineDistanceMeters": 299.9955 }, { "name": "places/ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "placeId": "ChIJWWIlNx7Lj4ARpe1E0ob-_GI", "displayName": { "text": "Din Tai Fung", "languageCode": "en" }, "types": [ "establishment", "food", "point_of_interest", "restaurant" ], "straightLineDistanceMeters": 157.70943 } ], "areas": [ { "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI", "displayName": { "text": "Westfield Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q", "displayName": { "text": "Valley Fair", "languageCode": "en" }, "containment": "WITHIN" }, { "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM", "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM", "displayName": { "text": "Central San Jose", "languageCode": "en" }, "containment": "WITHIN" } ] } }
Как получить информацию о перенесенном месте
Если место, упомянутое в вашем приложении, переехало, вы можете использовать поля movedPlace и movedPlaceId, чтобы получить информацию о новом месте.
Для мест, которые закрыты навсегда, в ответе на запрос информации о местах (New) в поле businessStatus возвращается значение CLOSED_PERMANENTLY, а поля movedPlace и movedPlaceId отсутствуют.
Для мест, которые переехали, информация о местах (New) возвращает CLOSED_PERMANENTLY в поле businessStatus и новое местоположение в полях movedPlace и movedPlaceId тела ответа.
Для мест, которые не перемещались, новый метод информации о местах не возвращает в теле ответа movedPlace или movedPlaceId.
В примере ниже запрашивается информация о магазине Marche IGA St-Canut в Квебеке (Канада):
curl -X GET -H 'Content-Type: application/json' \ -H 'x-Goog-Api-Key: API_KEY' \ -H 'X-Goog-FieldMask: id,displayName,businessStatus,movedPlace,movedPlaceId' \ https://places.googleapis.com/v1/places/ChIJUfQdGInVzkwRzAjmjzWB7CQ
В ответ на запрос будет получен следующий код:
{ "id": "ChIJUfQdGInVzkwRzAjmjzWB7CQ", "businessStatus": "CLOSED_PERMANENTLY", "displayName": { "text": "Marche IGA St-Canut", "languageCode": "en" }, "movedPlace": "places/ChIJ36QT7n8qz0wRDqVZ_UBlUlQ", "movedPlaceId": "ChIJ36QT7n8qz0wRDqVZ_UBlUlQ" }
Чтобы запросить информацию о новом месте, используйте название ресурса места в поле movedPlace в новом запросе информации о местах (New).
Если место несколько раз меняло адрес, для получения информации о текущем местоположении может потребоваться несколько связанных запросов информации о местах (New). Поля movedPlace и movedPlaceId в результатах поиска мест указывают только на следующее местоположение, а не на последнее известное. Место находится в текущем местоположении, если в теле ответа на запрос "информация о местах" (New) отсутствуют поля movedPlace и movedPlaceId.
Как найти компании, которые откроются в будущем
Вы можете запросить информацию о компаниях, которые планируют открыться в будущем.
Если в поле "Поиск поблизости (новый)" указана дата открытия, которая включает хотя бы месяц и наступит не позднее чем через 90 дней, то в поле openingDate будет указана эта дата.
В примере ниже показан запрос "Поиск поблизости (новый)" для компании, которая откроется в будущем в Нью-Медоусе, штат Айдахо:
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,businessStatus,openingDate" \ "https://places.googleapis.com/v1/places/ChIJp1-VoKWJplQRMz8g-7Wa3Do"
Ответ содержит статус компании и предполагаемую дату открытия:
{ "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do", "businessStatus": "FUTURE_OPENING", "openingDate": { "year": 2026, "month": 4, "day": 15 } }
Как получить информацию об остановке общественного транспорта
Чтобы получить информацию о станциях общественного транспорта, можно использовать Place Details (New). Тело ответа содержит информацию о станции, в том числе ее название, связанные транспортные агентства и маршруты общественного транспорта, которые обслуживают станцию. Кроме того, в ответе есть значок транспортного средства и цвета, которые можно использовать для отображения информации о станции.
В примере ниже показан запрос информации о Центральном вокзале Нью-Йорка.
curl -X GET \ -H "Content-Type: application/json" \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,transitStation" \ "https://places.googleapis.com/v1/places/ChIJLVaKiQFZwokRgcybX3K6Pzg"
Тело ответа содержит информацию о каждой станции в радиусе поиска, маршрутах, которые обслуживает станция, оповещениях, выпущенных транспортными агентствами на этой остановке, и сведениях об отправлении:
{ "id": "ChIJLVaKiQFZwokRgcybX3K6Pzg", "displayName": { "text": "Grand Central", "languageCode": "en" }, "transitStation": { "displayName": { "text": "Grand Central", "languageCode": "en" }, "agencies": [ { "displayName": { "text": "MTA New York City Transit", "languageCode": "en" }, "url": "http://www.mta.info/", "lines": [ { "id": "ChIJ420yFwBZwokR903kVZLSsFc", "vehicleType": "SUBWAY", "displayName": { "text": "42 St Shuttle", "languageCode": "en" }, "shortDisplayName": { "text": "S", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#808183", "url": "https://www.mta.info/schedules/subway/42-st-shuttle", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/S.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } }, { "id": "ChIJDdd_uEdfwokRHbLvWrdBdDM", "vehicleType": "SUBWAY", "displayName": { "text": "5 Train (Lexington Av Express)", "languageCode": "en" }, "shortDisplayName": { "text": "5 Line", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#00933C", "url": "https://www.mta.info/schedules/subway/5-train", "icon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/us-ny-mta/5.svg", "nameIncluded": true }, "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/subway2.svg" } } ... ] }, { "displayName": { "text": "MTA", "languageCode": "en" }, "url": "https://new.mta.info/", "lines": [ { "id": "ChIJcwVpzKpZwokR24EBeh8arww", "vehicleType": "BUS", "displayName": { "text": "United Nations - W 42 St Pier", "languageCode": "en" }, "shortDisplayName": { "text": "M42", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#1D59B3", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/bus2.svg" } } ] }, { "displayName": { "text": "Long Island Rail Road", "languageCode": "en" }, "url": "http://www.mta.info/lirr", "lines": [ { "id": "ChIJv9m8uWM56IkRUcVBQ6Q_In0", "vehicleType": "HEAVY_RAIL", "displayName": { "text": "Ronkonkoma Branch", "languageCode": "en" }, "shortDisplayName": { "text": "LIRR", "languageCode": "en" }, "textColor": "#FFFFFF", "backgroundColor": "#A626AA", "vehicleIcon": { "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg" } } ... ] } ], "stops": [ { "id": "ChIJRcemlf1YwokRhFqqw5jKBFM", "stopCode": { "text": "GCT" }, "location": { "latitude": 40.755161, "longitude": -73.975456 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJ57l2zANZwokRD1pyhuwpfKY", "signageText": { "text": "34 St-Hudson Yards & Main St-Flushing, Queens, 7", "languageCode": "en" }, "location": { "latitude": 40.750983, "longitude": -73.9750686 }, "wheelchairAccessibleEntrance": true }, { "id": "ChIJoVXJgQFZwokR1yzq_WVuEuc", "displayName": { "text": "E 42 St/Park Av", "languageCode": "en" }, "location": { "latitude": 40.7518199, "longitude": -73.9771918 }, "wheelchairAccessibleEntrance": true } ... ] } }
Получать информацию о входах и навигационных точках
Вы можете запросить входы и точки навигации для пункта назначения. Входы – это точки входа и выхода из места (например, разные ворота в аэропорту или торговом центре). Точки навигации определяют места на обочине, где должна заканчиваться навигация. Это полезно, чтобы направлять пользователей на нужную сторону дороги или в определенную точку высадки.
Точки навигации возвращают navigationPointToken. Вы можете передать этот токен в Navigation SDK (доступен для Android и iOS) или Routes API, чтобы направлять водителей к определенному местоположению. Подробнее о токенах точек навигации…
В следующем примере запрашиваются сведения о международном аэропорте Сан-Франциско (идентификатор места ChIJVVVVVYx3j4ARP-3NGldc8qQ), включая entrances и navigationPoints в маске поля:
curl -X GET -H 'Content-Type: application/json' \ -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: id,displayName,entrances,navigationPoints" \ https://places.googleapis.com/v1/places/ChIJVVVVVYx3j4ARP-3NGldc8qQ
Ответ содержит входы и точки навигации для места:
{ "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ", "displayName": { "text": "San Francisco International Airport", "languageCode": "en" }, "entrances": [ { "location": { "latitude": 37.6172154, "longitude": -122.3839724 } }, { "location": { "latitude": 37.6174073, "longitude": -122.384196 } }, ... ], "navigationPoints": [ { "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...", "displayName": { "text": "International Terminal Departures Level", "languageCode": "en" }, "location": { "latitude": 37.6153121, "longitude": -122.3900833 }, "travelModes": ["WALK"] }, { "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...", "displayName": { "text": "Domestic Garage - SFO Short Term Parking", "languageCode": "en" }, "location": { "latitude": 37.6157153, "longitude": -122.3885012 }, "travelModes": ["DRIVE", "WALK"], "usages": ["PARKING"] }, ... ] }
Попробовать
В API Explorer можно отправлять примеры запросов, чтобы ознакомиться с API и его возможностями.
Нажмите на значок API api в правой части страницы.
При необходимости измените параметры запроса.
Нажмите кнопку Execute (Выполнить). В диалоговом окне выберите аккаунт, который хотите использовать для запроса.
На панели APIs Explorer нажмите на значок полноэкранного режима , чтобы развернуть окно APIs Explorer.