Документация
Справочник JavaScript API
2.1.64 (текущая версия)
collection
interactivityModel
Интерфейсы

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

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]); 
});
Открыть пример в песочнице