Documentation
Reference
2.1.56 (current version)
collection
interactivityModel
Interfaces

Embedding Yandex panoramas

You can use the Panoramas API to put interactive Yandex panoramas on a webpage.

A panorama is added to the page separately from the map. Add it to any block type of DOM element. Panoramas are displayed using Canvas2D or WebGL technology.

Usage restrictions

The overall limit on requests to the Yandex.Maps API is 25,000 requests per day (for the free version). The number of API requests for the day is calculated from the total number of requests to the Yandex panoramas service, geocoding service, and routing service. The requests are weighted as follows: each request to the geocoding or routing service is equal to one request, while each request to the panoramas service (calling the panorama.locate function) is counted as five requests. This means that if the geocoding or routing services aren't used, the limit on using Yandex panoramas is 5,000 requests per day.

Attention! If you expect to exceed the maximum number of requests to the Yandex.Maps API, you should purchase the commercial version of the API.

Browser compatibility

To check whether the panorama player will work in the user's browser, you can use the static function panorama.isSupported():

if (panorama.isSupported()) {
    console.log("The API supports this browser.");
} else {
    console.log("This browser is not supported.");
}

Getting the panorama object

A panorama is described by the Panorama object. The properties of this object contain the panorama metadata, including its name, type (aerial or land), and the geographical coordinates of the point the panorama is bound to. The Panorama object also contains required information such as the panorama geometry, the size and URLs of tiles, and so on.

All information about a panorama is stored on Yandex servers. To get this information and base a Panorama object on it, use the panorama.locate() function. For input, pass the geographical coordinates of the point to get a panorama for. If a panorama doesn't exist at the specified point, the service searches for the nearest panorama in the vicinity of the point.

// Getting a Panorama object
var locateRequest = ymaps.panorama.locate([55.83403, 37.623370]);

// The ymaps.panorama.locate function returns a Promise object,
// which is resolved by an array with the found panorama, or an empty
// array, if a panorama wasn't found near the point.
locateRequest.then(
  function (panoramas) {
    if (panoramas.length) {
      console.log("Hooray, we found a panorama! " + panoramas[0]);       
    } else {
      console.log("No panoramas found for the specified point.");    
    }
  },
  function (err) {
    console.log("An error occurred when trying to get the panorama.");
  }
);

Displaying a panorama on a page

To show a panorama on a page, you need to create an instance of the panorama.Player class. Pass its constructor the ID of the DOM element that the panorama will be embedded in, along with the panorama object (see Getting the panorama object).

locateRequest.then(
  function (panoramas) {
    if (panoramas.length) {
      // Creating the panorama player on a page.
      var player = new ymaps.panorama.Player('div_id', panoramas[0], {
            // Panorama options. 
            // direction - viewing direction.
            direction: [0, -50]
          });
    } else {
      console.log("There aren't any panoramas for the specified point.");
    }
  }
);
Открыть пример в песочнице

The API provides a set of functions that you can use to control the panorama image — change the viewing direction or the zoom level, move to a connected panorama, and so on. For more information, see Controlling the panorama display.

Note. The API doesn't allow you to change the standard appearance of objects on the panorama (such as markers with house numbers and connection arrows).

Auxiliary function for working with the panorama

You can also use the panorama.createPlayer() auxiliary function to display a panorama on a page. For its parameters, pass the ID of the DOM element where the panorama will be embedded, and the coordinates of the point to open the panorama for. The function automatically checks for the existence of a panorama in the vicinity of the specified point. If successful, it creates an instance of the panorama player (the panorama.Player object) with the found panorama on the page.

// Using the auxiliary function to display a panorama on a page.
var createPlayer = ymaps.panorama.createPlayer('div_id', [55.83403, 37.623370], {
      // Panorama options.
      layer: 'yandex#airPanorama' 
    });

// If successful, the Promise object is resolved by the player.
createPlayer.then(function (player) {
  console.log("Panorama name: " + player.getPanorama().getName());
  // Setting a new viewing direction.
  player.setDirection([10, 10]); 
});
Открыть пример в песочнице