Фрагменты просмотра улиц

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

Если ваш платежный адрес находится в Европейской экономической зоне, то с 8 июля 2025 года использование вами Сервисов будет регулироваться Условиями использования платформы Google Карт для ЕЭЗ. Подробнее… Кроме того, определенный контент из Map Tiles API больше не будет возвращаться. Подробнее…

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

• Плитки Просмотра улиц в Google Картах
• Метаданные Просмотра улиц
• Значки Просмотра улиц

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

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

Совет. Подробную информацию вы найдете в статьях Street View Static API и Street View Service.

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

1. Получите токен сеанса. Убедитесь, что для параметра mapType задано значение streetview.

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

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

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

   2. Значки Просмотра улиц.

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

Примечание. На каждой панораме в Просмотре улиц должна быть информация об авторских правах. Строка, которая будет показываться, может отличаться для разных панорам. Чтобы получить информацию об авторских правах, запросите метаданные Просмотра улиц, а затем посмотрите поле copyright в ответе.

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

Чтобы получить доступ к изображениям и метаданным Просмотра улиц, вызовите один из четырех методов, описанных ниже.

Метод	Описание
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 x 16 пикселей. Максимальный размер – 250 x 600 пикселей.
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

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

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

С помощью panoIds вы можете:

• Запрос метаданных Просмотра улиц
• Запрос уменьшенных изображений для Просмотра улиц
• Запрос плиток Просмотра улиц

Примечание. Идентификаторы панорам являются временными. То есть они недолговечны. Как правило, идентификаторы панорам действительны только в течение одного пользовательского сеанса.

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

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

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

Текст об авторских правах, который должен показываться вместе с изображением Просмотра улиц.

reportProblemLink

Гиперссылка, по которой пользователи могут сообщить о проблемах с этой плиткой Просмотра улиц. Гиперссылка должна находиться в правом нижнем углу изображения и содержать текст, например "Сообщить о проблеме с этим изображением".

addressComponent

Структурированный объект Geocode, содержащий сведения об адресе панорамы. Дополнительную информацию можно найти в разделе Запросы и ответы геокодирования документации по Geocoding API.

links

Список идентификаторов панорам, связанных с этой. Также содержит заголовок, в котором находится ссылка. Например, если направление равно 180°, то связанная панорама находится к югу от текущей. Поскольку идентификаторы панорам являются временными, не следует полагаться на них дольше, чем в течение одного сеанса пользователя.

Значки Просмотра улиц

Вы можете запросить изображения Просмотра улиц в формате thumbnail. Значки – это немозаичные изображения с заданными пользователем размером, направлением, наклоном и зоной обзора. Значки имеют более низкое разрешение, чем фрагменты, и меньший размер файла. Чтобы запросить значок, отправьте GET-запрос к конечной точке thumbnail, как показано в примере кода ниже.

Примечание. Значения полей, заключенные в квадратные скобки в этом примере, показывают диапазоны. Например, height может быть от 16 до 250 пикселей.

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"

Рассмотрим следующий пример кода, который скачивает значок изображения Просмотра улиц, сделанного в Уистлере (Канада).

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. Если область просмотра имеет фиксированный размер, как в случае с изображением Просмотра улиц заданного размера, зона обзора представляет собой масштаб, где меньшие значения указывают на более высокий уровень масштабирования. Значение по умолчанию – 90.

Фрагменты изображений Просмотра улиц

Получив panoId, вы можете запросить фрагмент изображения Просмотра улиц. Запросы тайлов – это 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 – координаты нужного фрагмента Просмотра улиц. Уровни масштабирования панорам в Просмотре улиц должны находиться в диапазоне [0,5], где 0 – самая широкая зона обзора.

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

Примечание. Изображения для Просмотра улиц поступают из двух источников – Google (собственный контент, показ которого контролируется компанией) и пользователей сервиса (общедоступный пользовательский контент). Обратите внимание, что использовать только один источник изображений для Просмотра улиц невозможно. Подробнее о политике конфиденциальности изображений Просмотра улиц…

Ответы Street View Tiles API

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

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

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

Совет. Чтобы рассчитать максимальные значения x и y, разделите imageHeight и imageWidth на tileHeight и tileWidth.

Сведения об авторских правах.

Для каждой панорамы в Просмотре улиц необходимо указывать информацию об авторских правах. Строка, которая будет показываться, может отличаться для разных панорам. Чтобы получить информацию об авторских правах, запросите метаданные Просмотра улиц, а затем посмотрите поле copyright в ответе. Подробнее об атрибуции данных…