Плитки просмотра улиц аналогичны 2D-плиткам, за исключением того, что они содержат панорамные изображения, снятые на уровне улицы. С помощью Street View вы можете исследовать достопримечательности мира, видеть чудеса природы и заходить в такие места, как музеи, арены, рестораны или малые предприятия. Эта конечная точка API дает вам доступ к:
- Плитки просмотра улиц Google Maps
- Метаданные Просмотра улиц
- Миниатюры просмотра улиц
Вы можете соединить фрагменты изображений, снятые с уровня улицы, чтобы создать реальный панорамный эффект. Вы можете запросить до 100 идентификаторов панорам для набора мест (например, маршрута) и получить более подробные метаданные о положении камеры.
Зрителю необходимо сшить плитки просмотра улиц вместе. Например, средство просмотра пользовательских панорам Street View .
Получив ключ API, вы сможете получить доступ к изображениям Street View, выполнив следующие действия.
Получите токен сеанса . Обязательно установите для
mapType
значениеstreetview
.Используйте токен сеанса, чтобы получить идентификатор панорамы (panoId) одного или нескольких географических местоположений.
Используйте идентификаторы панорамы из ответа поиска panoId, чтобы получить:
Метаданные Просмотра улиц . Вы также можете получить метаданные Street View, передав набор координат и радиус.
Методы просмотра улиц
Вы можете получить доступ к изображениям и метаданным Street View, вызвав один из следующих четырех методов.
Метод | Описание |
---|---|
https://tile.googleapis.com/v1/streetview/tiles | Возвращает отдельные плитки просмотра улиц. Вы можете получить плитки просмотра улиц с шестью уровнями масштабирования: от 512 пикселей до 13 312 пикселей. |
https://tile.googleapis.com/v1/streetview/panoIds | Позволяет выполнять массовый поиск по 100 локациям. Возвращает идентификаторы панорам для всех мест с изображениями. |
https://tile.googleapis.com/v1/streetview/thumbnail | Возвращает миниатюру изображения сцены просмотра улиц в формате JPEG. Позволяет указать заголовок, шаг, размеры и поле зрения. Минимальные размеры — 16х16 пикселей. Максимальные размеры — 250x600 пикселей. |
https://tile.googleapis.com/v1/streetview/metadata | Предоставляет подробную информацию об указанной панораме. Подробная информация включает соответствующий адрес и ссылки на соседние панорамы. |
Поиск панорам в Просмотре улиц
Вы можете найти идентификатор панорамы одного или нескольких географических мест, передав их координаты ( lat
, lng
) методу panoIds
. Тело запроса — это объект JSON, который содержит массив locations
и, при необходимости, radius
, как показано в следующем примере кода JSON.
curl -X POST -d '{ "locations": [ {"lat": -33.883837, "lng": 151.209307}, {"lat": -33.883700, "lng": 151.210307}, {"lat": 0, "lng": 0} ], "radius": 50 }' \ -H 'Content-Type: application/json' \ "https://tile.googleapis.com/v1/streetview/panoIds?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY"
-
locations
- Массив
locations
должен содержать хотя бы один набор значений координат, но вы можете включить больше — максимум до 100. -
radius
- Значение
radius
(измеряется в метрах) определяет радиус круга вокруг заданной локации, в котором осуществляется поиск панорам. Значение по умолчанию — 50 метров.
Паноидный ответ
API плиток карты пытается найти панораму, ближайшую к каждому местоположению, а затем возвращает идентификаторы панорам. Успешный запрос panoIds
возвращает объект JSON, содержащий массив panoIds
. Массив содержит список идентификаторов панорам в том порядке, в котором вы их запросили. Если API Map Tiles не может найти панорамы для запрошенных вами местоположений, то в этом месте массива возвращается пустая строка. Пример см. в следующем коде JSON.
{
"panoIds": [
"ACfH-n2HcBvRry_3oc9grw",
"f5DJZatBAAAXHlooS2wKbw",
""
]
}
Вы можете использовать panoIds
для:
- Запросить метаданные Просмотра улиц
- Запросить миниатюры Просмотра улиц
- Запросить плитки для просмотра улиц
Метаданные Просмотра улиц
Запросы метаданных Street View получают информацию о панорамах. Запрос метаданных Просмотра улиц — это запрос HTTPS GET. Получить информацию о панорамах можно одним из двух способов:
Если вы передадите
pano_id
, Map Tiles API вернет метаданные для этой панорамы.Но если вы передадите
lat
иlng
, Map Tiles API вернет метаданные для ближайшей панорамы в пределах заданного радиуса поиска.
Передать набор координат и радиус
curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY &lat=lat &lng=lng &radius=meters"
Поскольку идентификаторы панорам являются временными, мы рекомендуем передавать набор координат и значение radius
в исходном запросе метаданных Просмотра улиц. Пример см. в следующем фрагменте кода.
curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &lat=47.62066 &lng=-122.34923 &radius=50"
Передайте panoId изображения Street View
curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &panoId=panoId"
Ответ метаданных
Следующий код JSON является примером типичного ответа метаданных.
{
"panoId": "rZ9KeTyhA11i0VppYNzsSg",
"lat": 37.420864219339165,
"lng": -122.08446528377291,
"imageHeight": 6656,
"imageWidth": 13312,
"tileHeight": 512,
"tileWidth": 512,
"heading": 94.35,
"tilt": 88.39652,
"roll": 1.7181772,
"imageryType": "outdoor",
"date": "2023-01",
"copyright": "© 2023 Google",
"reportProblemLink": "https://cbks0.googleapis.com/cbk?output=report&panoid=rZ9KeTyhA11i0VppYNzsSg&cb_client=api&cbp=1,0,,0,0&hl=en-US&gl=us",
"addressComponents": [
{
"longName": "United States",
"shortName": "United States",
"types": [
"country"
]
},
{
"longName": "Mountain View, California",
"shortName": "Mountain View, California",
"types": [
"locality"
]
},
{
"longName": "Charleston Rd",
"shortName": "Charleston Rd",
"types": [
"route"
]
},
{
"longName": "1635",
"shortName": "1635",
"types": [
"street_number"
]
}
],
"links": [
{
"panoId": "Yw4pqzA4FEq1qs-BwZSvSQ",
"heading": 274.47998046875,
"text": "Charleston Rd"
},
{
"panoId": "1cODYwFRw1aZ45IignDIMw",
"heading": 94.47999572753906,
"text": "Charleston Rd"
}
]
}
Следующий список содержит определения полей в тексте ответа.
-
panoId
- Уникальный идентификатор этой панорамы. Не следует полагаться на то, что идентификаторы Panorama действительны дольше одного пользовательского сеанса.
-
lat
,lng
- Координаты (широта и долгота) панорамы. Эти значения могут отличаться от координат, которые вы передали в запросе, поскольку местоположение привязывается к ближайшей панораме.
-
imageHeight
,imageWidth
- Размеры сшиваемого панорамного изображения.
-
tileHeight
,tileWidth
- Размеры одного фрагмента панорамы.
-
heading
- Курс компаса, измеренный в градусах, по часовой стрелке от севера. Направления возвращаются в диапазоне [0,360], где 0 соответствует строгому северу.
-
tilt
- Наклон панорамы измеряется в градусах от южного полюса панорамы до горизонта. Возвращаемые значения находятся в диапазоне [0, 180]. Значение 90 градусов указывает на то, что горизонт уже выровнен по экватору панорамы.
-
roll
- Вращение по часовой стрелке вокруг луча зрения, примененное к панораме для выравнивания горизонта. Возвращаемые значения находятся в диапазоне [0, 360].
-
imageryType
- Указывает тип изображения. Допустимые значения:
indoor
иoutdoor
. -
date
- Дата, когда было сделано изображение. Не на всех изображениях есть данные о дате. Но если оно доступно, это поле содержит комбинацию года (ГГГГ) и месяца (ММ). Например: 2023-05 или 2024.
-
copyright
- Текст об авторских правах, который необходимо отображать в качестве указания авторства вместе с изображением Просмотра улиц.
-
reportProblemLink
- Гиперссылка, которую ваши пользователи смогут использовать для сообщения о проблемах с этой плиткой просмотра улиц. Эту гиперссылку необходимо отобразить в правом нижнем углу изображения, и она должна содержать текст ссылки, например «Сообщить о проблеме с этим изображением».
-
addressComponent
- Структурированный геокод , содержащий подробную информацию об адресе панорамы. Дополнительную информацию см. в разделе Запросы и ответы геокодирования в документации API геокодирования.
-
links
- Список идентификаторов панорам, которые ссылаются на эту панораму. Также содержит заголовок, по которому находится ссылка. Например, если курс равен 180°, то связанная панорама расположена южнее текущей панорамы. Обратите внимание: из-за временного характера идентификаторов панорам не следует полагаться на них более чем для одного пользовательского сеанса.
Миниатюры просмотра улиц
Вы можете запросить изображения Street View в формате thumbnail
. Миниатюры — это изображения без мозаики с заданным пользователем размером, заголовком, шагом и полем обзора. Миниатюры изображений имеют более низкое разрешение, чем плитки, и имеют меньший размер файла. Вы делаете запрос миниатюры, отправляя запрос GET к конечной точке thumbnail
, как показано в следующем прототипе кода.
curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &panoId=panoId &height=FROM_16_TO_250 &width=FROM_16_TO_600 &pitch=FROM-90_TO_90 &yaw=FROM-360_TO_360 &fov=FROM_30_TO_120"
Рассмотрим следующий пример кода, который загружает миниатюру изображений Street View, сделанных в Уистлере, Канада.
curl "https://tile.googleapis.com/v1/streetview/thumbnail?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &panoId=Zzl28rqGJgaL2IdkUleP8A &height=200 &width=200 &pitch=0 &yaw=250 &fov=80" --output /tmp/example_thumbnail.png
Обязательные параметры
-
panoId
- Уникальный идентификатор нужной миниатюры. Вы можете получить значения идентификатора панорамы из конечной точки
panoIds
или из конечной точкиmetadata
— оба из них принимают географические координаты и возвращают соответствующийpanoId
. -
session
- Действительный токен сеанса .
-
key
- Ваш API-ключ .
Дополнительные параметры
-
height
- Указывает высоту миниатюры в пикселях в диапазоне от 16 до 250 пикселей. Если вы не укажете высоту, по умолчанию будет установлено максимально допустимое значение — 250 пикселей. Если вы укажете значение, выходящее за пределы диапазона, миниатюра будет привязана к ближайшему допустимому значению.
-
width
- Указывает ширину миниатюры в пикселях в диапазоне от 16 до 600 пикселей. Если вы не укажете ширину, по умолчанию она будет равна максимально допустимому значению 600 пикселей. Если вы укажете значение, выходящее за пределы диапазона, миниатюра будет привязана к ближайшему допустимому значению.
-
pitch
- Определяет угол камеры вдоль вертикальной оси. Допустимые значения находятся в диапазоне
-90
до90
(включительно). Значение по умолчанию — 0. -
yaw
- Определяет направление камеры по горизонтальной оси. Допустимые значения находятся в диапазоне
-360
до360
(включительно). Значение по умолчанию — 0. -
fov
- Указывает горизонтальное поле обзора, выраженное в градусах, с максимальным значением 120. При работе с областью просмотра фиксированного размера, как и в случае с изображением Street View заданного размера, поле обзора представляет собой масштаб; где меньшие значения определяют более высокий уровень масштабирования. Значение по умолчанию — 90.
Фрагменты изображений Просмотра улиц
Получив panoId
, вы можете запросить фрагмент изображения Street View. Запросы плиток — это запросы HTTPS GET. Рассмотрим следующий пример.
curl "https://tile.googleapis.com/v1/streetview/tiles/z/x/y?session=YOUR_SESSION_TOKEN &key=YOUR_API_KEY &panoId=panoId"
В этом примере кода z
— это уровень масштабирования, а x
и y
— координаты нужного фрагмента просмотра улиц. Уровни масштабирования в панорамах Street View должны находиться в диапазоне [0,5], где 0 соответствует самому широкому полю обзора.
Уровень масштабирования | Приблизительное поле зрения |
---|---|
0 | 360° |
1 | 180° |
2 | 90° |
3 | 45° |
4 | 22,5° |
5 | 11,25° |
Ответы на плитки просмотра улиц
Успешный запрос плитки Просмотра улиц возвращает изображение того формата и размера, которые вы указали в ответе createSession
.
При нулевом уровне масштабирования вся панорама преобразуется в плитку с размерами tileWidth
на tileHeight
. Поскольку панорамы больше по размеру x, плитка будет содержать пустое пространство по измерению y:
На пятом уровне масштабирования используется полноразмерная панорама, разделенная на фрагменты.
Информация об авторских правах
Вы должны отображать информацию об авторских правах в каждой панораме Street View. Строка для отображения может различаться в зависимости от панорамы. Чтобы получить информацию об авторских правах, вам необходимо запросить метаданные Street View , а затем вы можете обратиться к полю copyright
в ответе. Дополнительную информацию см. в разделе Атрибуция данных .