Плитки просмотра улиц

Разработчики Европейской экономической зоны (ЕЭЗ)

Пример плитки Street View

Тайлы Street View похожи на 2D-тайлы , но содержат панорамные изображения, снятые на уровне улиц. С Street View вы можете исследовать мировые достопримечательности, любоваться природными чудесами и заходить в такие места, как музеи, арены, рестораны и небольшие предприятия. Эта конечная точка API предоставляет вам доступ к:

  • Плитки просмотра улиц в Google Картах
  • Метаданные Street View
  • Миниатюры Street View

Вы можете склеивать фрагменты изображений, снятых с уровня улицы, создавая эффект настоящей панорамы. Кроме того, вы можете запросить до 100 идентификаторов панорам для набора местоположений (например, маршрута) и получить более подробные метаданные о положении камеры.

Для объединения фрагментов Street View требуется средство просмотра. Например, средство просмотра пользовательских панорам Street View .

Получив ключ API, вы сможете получить доступ к изображениям Street View, выполнив следующие шаги.

  1. Получите токен сеанса . Обязательно установите значение mapType на streetview .

  2. Используйте токен сеанса для получения идентификатора панорамы (panoId) одного или нескольких географических местоположений.

  3. Используйте идентификаторы панорам из ответа поиска panoId, чтобы получить:

    1. Метаданные Street View . Вы также можете получить метаданные Street View, передав набор координат и радиус.

    2. Миниатюры Street View .

    3. Плитки Street View .

Методы просмотра улиц

Вы можете получить доступ к изображениям и метаданным Street View, вызвав один из следующих четырех методов.

Метод Описание
https://tile.googleapis.com/v1/streetview/tiles Возвращает отдельные фрагменты Street View. Вы можете получить фрагменты Street View с шестью уровнями масштабирования: от 512 до 13 312 пикселей.
https://tile.googleapis.com/v1/streetview/panoIds Позволяет выполнять массовый поиск по 100 локациям. Возвращает идентификаторы панорам для всех локаций с изображениями.
https://tile.googleapis.com/v1/streetview/thumbnail Возвращает миниатюру изображения сцены Street View в формате JPEG. Позволяет указать заголовок, наклон, размеры и поле обзора. Минимальный размер — 16x16 пикселей. Максимальный размер — 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 метров.

Ответ PanoId

API Map Tiles пытается найти ближайшую к каждому местоположению панораму, а затем возвращает их идентификаторы. Успешный запрос panoIds возвращает JSON-объект, содержащий массив panoIds . Массив содержит список идентификаторов панорам в порядке запроса. Если API Map Tiles не может найти ни одной панорамы для запрошенных местоположений, в этом месте массива возвращается пустая строка. Пример см. в следующем JSON-коде.

{
  "panoIds": [
    "ACfH-n2HcBvRry_3oc9grw",
    "f5DJZatBAAAXHlooS2wKbw",
    ""
  ]
}

Вы можете использовать panoIds для:

Метаданные Street View

Запросы метаданных Street View позволяют получить информацию о панорамах. Запрос метаданных Street View — это HTTPS-запрос GET. Вы можете получить информацию о панорамах одним из двух способов:

  • Если вы передадите pano_id , то Map Tiles API вернет метаданные для этой панорамы.

  • Но если вы передадите lat и lng , то API Map Tiles вернет метаданные для ближайшей панорамы в пределах заданного радиуса поиска.

Передать набор координат и радиус 

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=lat&lng=lng&radius=meters"

Поскольку идентификаторы панорам являются временными, мы рекомендуем передавать набор координат и значение radius в начальном запросе метаданных Street View. Пример см. в следующем фрагменте кода.

curl "https://tile.googleapis.com/v1/streetview/metadata?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY&lat=47.62066&lng=-122.34923&radius=50"

Передайте идентификатор панорамы изображения 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
Уникальный идентификатор этой панорамы. Не стоит полагаться на то, что идентификаторы панорам будут действительны дольше одного сеанса пользователя.
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
Текст об авторских правах, который необходимо отобразить в качестве атрибуции вместе с изображением Street View.
reportProblemLink
Гиперссылка, по которой ваши пользователи смогут сообщить о проблемах с этим фрагментом изображения улицы. Необходимо разместить эту гиперссылку в правом нижнем углу изображения и добавить текст, например, «Сообщить о проблеме с этим изображением».
addressComponent
Структурированный геокод , содержащий информацию об адресе панорамы. Подробнее см. в разделе «Запросы и ответы геокодирования» в документации Geocoding API.
links
Список идентификаторов панорам, ссылающихся на данную панораму. Также содержит направление, по которому находится ссылка. Например, если направление — 180°, то связанная панорама расположена южнее текущей. Обратите внимание, что из-за временного характера идентификаторов панорам не следует использовать их более чем в течение одного сеанса пользователя.

Миниатюры Street View

Вы можете запросить изображения 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.

Плитки изображений Street View

Получив 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. Уровень масштабирования панорам Street View должен находиться в диапазоне [0,5], где 0 соответствует самому широкому полю обзора.

Уровень масштабирования Примерное поле зрения
0 360°
1 180°
2 90°
3 45°
4 22,5°
5 11,25°

Ответы Street View Tiles

Успешный запрос фрагмента Street View возвращает изображение в формате и размере, которые вы указали в ответе createSession .

Результат успешного запроса Tile

При нулевом уровне масштабирования вся панорама уменьшается до размера тайла размером tileWidth и tileHeight . Поскольку панорамы больше по оси X, тайл будет содержать пустое пространство по оси Y:

Уровень масштабирования нулевой

На пятом уровне масштабирования используется полноразмерная панорама, разделенная на фрагменты.

Информация об авторских правах должна отображаться на каждой панораме Street View. Отображаемая строка может различаться в зависимости от панорамы. Чтобы получить информацию об авторских правах, необходимо запросить метаданные Street View , а затем обратиться к полю copyright в ответе. Подробнее см. в разделе «Атрибуция данных» .