Вставка панорам Яндекса

API плеера панорам позволяет размещать на странице сайта интерактивные панорамы Яндекса.

Панорама добавляется на страницу отдельно от карты, в любой DOM-элемент блочного типа. Для отображения панорамы используется технология Canvas2D либо WebGL.

Ограничения на использование

Общий лимит запросов к сервису API Карт составляет 25 000 запросов в сутки (для бесплатной версии). Суточное количество запросов к API рассчитывается на основе общего количества обращений к сервису панорам Яндекса, а также к геокодеру и маршрутизатору. При этом действует следующее правило: одно обращение к геокодеру или маршрутизатору приравнивается к одному запросу, а одно обращение к панорамам Яндекса (вызов функции panorama.locate) — к пяти запросам. Таким образом, если сервисы геокодирования или маршрутизации использоваться не будут, лимит на использование панорам Яндекса составляет 5 000 запросов в сутки.

Внимание. Если предполагаемое число запросов к сервису API Карт больше установленного лимита, следует приобрести платную версию API.

Совместимость с браузерами

Чтобы проверить, будет ли работать плеер панорам в браузере пользователя, можно воспользоваться статической функцией panorama.isSupported():

if (panorama.isSupported()) {
    console.log("API поддерживает данный браузер.");
} else {
    console.log("Данный браузер не поддерживается.");
}

Получение объекта панорамы

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

Вся информация о панораме хранится на серверах Яндекса. Чтобы получить эту информацию и на ее основе сформировать объект Panorama, необходимо воспользоваться функцией panorama.locate(). На вход ей передаются географические координаты точки, для которой требуется получить панораму. Если в заданной точке панорамы не существует, то будет выполнен поиск ближайшей панорамы в окрестностях этой точки.

// Получение объекта Panorama.
var locateRequest = ymaps.panorama.locate([55.83403, 37.623370]);

// Функция ymaps.panorama.locate возвращает Promise-объект,
// который разрешится массивом с найденной панорамой либо пустым
// массивом, если в окрестностях точки панорам не нашлось.
locateRequest.then(
  function (panoramas) {
    if (panoramas.length) {
      console.log("Ура, нашлась панорама " + panoramas[0]);       
    } else {
      console.log("Для заданной точки не найдено ни одной панорамы.");    
    }
  },
  function (err) {
    console.log("При попытке получить панораму возникла ошибка.");
  }
);

Отображение панорамы на странице

Чтобы показать панораму на странице, необходимо создать экземпляр класса panorama.Player. Его конструктору следует передать идентификатор DOM-элемента, в который будет встроена панорама, а также объект панорамы (см. Получение объекта панорамы).

locateRequest.then(
  function (panoramas) {
    if (panoramas.length) {
      // Создание на странице плеера панорам.
      var player = new ymaps.panorama.Player('div_id', panoramas[0], {
            // Опции панорамы. 
            // direction - направление взгляда.
            direction: [0, -50]
          });
    } else {
      console.log("В заданной точке нет панорам.");
    }
  }
);
Открыть пример в песочнице

API предоставляет набор функций, с помощью которых можно управлять отображением панорамы — изменять направление взгляда или уровень масштабирования, переходить на смежную панораму и др. Подробнее см. Управление отображением панорамы.

Примечание. API не позволяет изменять стандартный внешний вид объектов на панораме (маркеров с номерами домов и стрелки переходов).

Вспомогательная функция для работы с панорамой

Показать панораму на странице можно также при помощи вспомогательной функции panorama.createPlayer(). В качестве параметров ей нужно передать идентификатор DOM-элемента, в который будет встроена панорама, а также координаты точки, для которой требуется открыть панораму. Функция автоматически выполнит проверку на наличие панорамы в окрестностях заданной точки и в случае успеха создаст на странице экземпляр плеера (объект panorama.Player) с найденной панорамой.

// Отображение панорамы на странице с помощью вспомогательной функции.
var createPlayer = ymaps.panorama.createPlayer('div_id', [55.83403, 37.623370], {
      // Опции панорамы.
      layer: 'yandex#airPanorama' 
    });

// В случае успеха Promise-объект разрешится плеером.
createPlayer.then(function (player) {
  console.log("Имя панорамы: " + player.getPanorama().getName());
  // Установим новое направление взгляда.
  player.setDirection([10, 10]); 
});
Открыть пример в песочнице