Плитки просмотра улиц аналогичны 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-
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 в ответе. Дополнительную информацию см. в разделе Атрибуция данных .