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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Метод Описание
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, как показано в примере кода ниже.

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°

Ответы API "Плитки Просмотра улиц"

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

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

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

Уровень масштабирования 0

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

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