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

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

Запрос изображения Просмотра улиц – это URL с протоколом HTTP в следующем формате:

https://maps.googleapis.com/maps/api/streetview?parameters

Изображение определяется с помощью параметров запроса. Параметры разделяются амперсандами (&) в соответствии со стандартом написания URL. Ниже перечислены допустимые параметры и их возможные значения.

Обязательные параметры

Выполните одно из следующих действий:

  • location может быть текстовой строкой (например, Chagrin Falls, OH), парой координат широты и долготы (40.457375,-80.009353) или идентификатором места с префиксом place_id: (например, place_id:ChIJj61dQgK6j4AR4GeTYWZsKWw). Значение должно быть закодировано в URL. Поэтому перед отправкой запроса преобразуйте адреса, например "City Hall, New York, NY" в "City+Hall,New+York,NY". Street View Static API привязывается к панорамной фотографии, ближайшей к местоположению. Если вы указываете текстовую строку адреса или идентификатор места, API может использовать другое местоположение камеры, чтобы лучше показать указанное место. Если вы указываете координаты широты и долготы, API ищет в радиусе 50 метров фотографию, которая находится ближе всего к этому месту. Поскольку изображения Просмотра улиц периодически обновляются, а фотографии могут быть сделаны из немного разных позиций, возможно, что при обновлении изображений ваш объект location будет привязан к другой панораме.

Альтернативный вариант:

  • pano – идентификатор панорамы. Идентификаторы панорам могут со временем меняться, поэтому не сохраняйте их. Вместо этого сохраните адрес или координаты широты и долготы, чтобы вы могли обновить идентификатор панорамы. Подробнее о том, как обновить идентификаторы удаленных панорам…

А также:

  • size определяет размер изображения в пикселях. Размер указывается в формате {width}x{height}. Например, при значении size=600x400 будет возвращено изображение шириной 600 пикселей и высотой 400 пикселей.
  • key позволяет отслеживать использование API приложения в консоли Google Cloud и гарантирует, что Google сможет связаться с вами по поводу вашего приложения, если это необходимо. Подробнее о том, как получить ключ и подпись…

Обновление идентификаторов удаленных панорам

Если при попытке получить идентификатор панорамы вы получаете ZERO_RESULTS или не получаете никакого значения, значит идентификатор панорамы был удален и его нужно обновить.

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

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

Необязательные параметры

  • signature (рекомендуется) – это цифровая подпись, которая используется для проверки того, что у сайта, создающего запросы с помощью вашего ключа API, есть на это разрешение. Запросы без цифровой подписи могут не выполняться. Подробнее о том, как получить ключ и подпись…

    Примечание. Для бывших клиентов тарифного плана Premium платформы Google Карт цифровая подпись обязательна. Подробнее о параметрах аутентификации для клиентов с тарифным планом Premium…

  • heading указывает направление камеры по компасу. Допустимые значения – от 0 до 360 (оба значения указывают на север, 90 – на восток, а 180 – на юг). Если направление не указано, то рассчитывается значение, при котором камера направлена на заданную точку location из места, где была сделана ближайшая фотография.
  • fov (значение по умолчанию – 90) определяет горизонтальную зону обзора изображения в градусах. Максимально допустимое значение – 120. Если область просмотра имеет фиксированный размер, как в случае с изображением Просмотра улиц, то зона обзора по сути представляет собой масштаб, причем меньшие значения соответствуют большему масштабу.


    Скриншот с широкой зоной обзора, на котором видны потолок, стены, пол и окно резервуара внутри аквариума. Скриншот с изображением крупного плана, на котором показаны детали фотографии в режиме просмотра улиц внутри аквариума.
    (Слева: fov=120; справа: fov=20)

  • pitch (по умолчанию – 0) – определяет угол наклона камеры вверх или вниз относительно автомобиля Просмотра улиц. В большинстве случаев, хотя и не всегда, камера направлена горизонтально. Положительные значения направляют камеру вверх (90 – вертикально вверх), а отрицательные – вниз (-90 – вертикально вниз).
  • radius (по умолчанию – 50) – задает радиус в метрах, в пределах которого нужно искать панораму, с центром в указанных широте и долготе. Допустимые значения – неотрицательные целые числа.
  • return_error_code указывает, должен ли API возвращать код ошибки, если изображение не найдено (404 NOT FOUND) или в ответ на недопустимый запрос (400 BAD REQUEST). Допустимые значения: true и false. Если задано значение true, вместо стандартного серого изображения возвращается сообщение об ошибке. Это позволяет не делать отдельный вызов для проверки доступности изображения.
  • source (значение по умолчанию – default) – ограничение поиска в Просмотре улиц выбранными источниками. Допустимые значения:
    • default – источники Просмотра улиц по умолчанию (поиск не ограничен заданными источниками);
    • google – только официальные коллекции Google
    • outdoor – только уличные фотографии Коллекции, снятые в помещении, не включаются в результаты поиска. Обратите внимание, что для указанного местоположения может не найтись панорамы, снятой вне помещений. Обратите внимание, что поиск возвращает только те панорамы, для которых можно определить, где они сняты – в помещении или на улице. Например, фотосферы не возвращаются, поскольку неизвестно, где они были сделаны – в помещении или на улице.

Это пример запроса.

https://maps.googleapis.com/maps/api/streetview?size=600x300&location=46.414382,10.013988&heading=151.78&pitch=-0.76&key=YOUR_API_KEY&signature=YOUR_SIGNATURE
Скриншот фотографии с видом на улицу, на которой показаны электрифицированные железнодорожные пути.

Изображения не найдены

Если для какого-либо местоположения нет изображений Просмотра улиц, Street View Static API возвращает стандартное серое изображение с текстом "К сожалению, у нас нет изображений для этого места", как показано в следующем примере:

Скриншот стандартного изображения, которое показывается, когда для указанного местоположения нет снимков. На светло-коричневом фоне виден текст "Изображений нет".
Рисунок. Стандартное изображение, которое показывается, если для указанного местоположения нет изображений.

Показывать только допустимые изображения

Чтобы избежать показа общего изображения и обеспечить показ только действительных изображений Street View Static API, следуйте этим рекомендациям:

  • Задайте для параметра return_error_code значение true. В этом случае, если для указанного местоположения нет изображения, Street View Static API возвращает ошибку 404 NOT FOUND вместо стандартного серого изображения.
  • Запросите метаданные изображения Просмотра улиц, чтобы определить, доступны ли изображения для указанного местоположения, прежде чем отправлять запрос.