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

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

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

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

  • Плитки просмотра улиц в Google Maps
  • Метаданные 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, вызвав один из следующих четырех методов.

Метод Описание
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 Возвращает миниатюру изображения JPEG сцены Street View. Позволяет указать заголовок, шаг, размеры и поле зрения. Минимальные размеры — 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 , то API Map Tiles вернет метаданные для этой панорамы.

  • Но если вы передадите 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"

Передайте 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
Уникальный идентификатор этой панорамы. Не стоит полагаться на то, что идентификаторы панорам будут действительны дольше, чем один сеанс пользователя.
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
Структурированный геокод , содержащий сведения об адресе панорамы. Для получения дополнительной информации см. Запросы и ответы геокодирования в документации 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 (включительно). Значение по умолчанию s 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

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

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

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

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

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

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