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

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

• Плитки просмотра улиц Google Maps
• Метаданные Просмотра улиц
• Миниатюры просмотра улиц

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

Зрителю необходимо сшить плитки просмотра улиц вместе. Например, средство просмотра пользовательских панорам Street View .

Совет. Дополнительные сведения см. в разделах Статический API просмотра улиц и Служба просмотра улиц .

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

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

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

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

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

   2. Миниатюры просмотра улиц .

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

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

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

Вы можете получить доступ к изображениям и метаданным 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?session=YOUR_SESSION_TOKEN&key=YOUR_API_KEY"

locations

Массив locations должен содержать хотя бы один набор значений координат, но вы можете включить и больше — максимум до 100.

radius

Значение radius (измеряется в метрах) определяет радиус круга вокруг заданной локации, в котором осуществляется поиск панорам. Значение по умолчанию — 50 метров.

Паноидный ответ

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

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

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

• Запросить метаданные Просмотра улиц
• Запросить миниатюры Просмотра улиц
• Запросить плитки для просмотра улиц

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

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

Запросы метаданных 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 , как показано в следующем прототипе кода.

Примечание. Значения полей, заключенные в квадратные скобки, в этом примере показывают диапазоны. Например, 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"

Рассмотрим следующий пример кода, который загружает миниатюру изображений 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°

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

Ответы на плитки просмотра улиц

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

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

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

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

Информация об авторских правах

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