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

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

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

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

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

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

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

  • Параметр location может быть текстовой строкой (например, Chagrin Falls, OH) или парой координат широты и долготы (40.457375,-80.009353). Он должен быть закодирован в формате 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 – источники Просмотра улиц по умолчанию (поиск не ограничен заданными источниками);
    • 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 вместо стандартного серого изображения.
  • Запросите метаданные изображения Просмотра улиц, чтобы определить, доступны ли изображения для указанного местоположения, прежде чем отправлять запрос.