JS Panorama

Panorama on Mapy.com is a feature similar to Street View, allowing you to explore most streets in the Czech Republic and look around in all directions.

There are currently two ways for developers to use Panorama:

JS Panorama – (described in this chapter) A JavaScript component that provides your users with an experience similar to Mapy.com. It enables free navigation and movement within the panoramic view directly in your application.
Static Panorama – A REST API that returns a static image of the view from a selected location. You can simply embed it using <img src="...">, specifying the location and direction in the parameters. The image is fixed and cannot be rotated further. Read more in the chapter Static Panorama API.

JS Panorama Component

JavaScript component for displaying panoramic images from all over the Czech Republic.

This “panorama viewer” handles the display of spherical images on your website and allows users to look around or move to adjacent images.

The component itself manages loading the necessary data via REST API.

For concrete examples, see the Panorama tutorials.

The most recent Panorama capturing on Mapy.com took place in 2021–2023, when the entire Czech Republic was gradually updated. Approximately one third of the territory was captured each year, and every year, 21 selected cities—including Prague, Brno, and Ostrava—were repeatedly recaptured.

Panorama Controls

The user can look around in the panorama using the mouse, or with the keyboard (arrow keys left/right or “a”/”d”).

If navigation between images is enabled (showNavigation:true), the user can move using the mouse (by clicking navigation arrows or areas of other images) or the keyboard (arrow keys up/down or “w”/”s”).

Panorama Data Consumption

A panorama (one sphere) is not downloaded as one large photo, but is composed of individual panorama tiles. The usual size of a panorama is 16×8 tiles.

The JS viewer automatically manages downloading the necessary tiles. It does not download the entire sphere, but only those tiles that are in the displayed view.

Panorama usage (in tiles) is then charged according to the REST API price list.

Using the Library

To use the panorama, you need to add this script to the header.

<script type="text/javascript" src='https://api.mapy.cz/js/panorama/v1/panorama.js'></script>

With this script, you have access to the Panorama class, which exposes a single panoramaFromPosition() function.

Function panoramaFromPosition()

This function is used for displaying the panorama at specific coordinates. It searches for the nearest panorama to the given coordinates within a specified radius.

Input Parameters

parent	parent HTML element for attaching the panorama
lon, lat	coordinates around which the nearest panorama is searched, up to the specified radius (see the radius parameter)
apiKey	API key for REST API
Optional Parameters
radius	Maximum radius for finding the panorama. In meters. default value: 50 m
yaw	Orientation relative to the north Possible values: “auto” – default value, orientation follows the direction of the panorama “point” – orientation towards the input coordinates number – custom value within the range 0 – 2 * Math.PI (0 – north)
pitch	Tilt (- up, + down) Possible values: +-Math.PI default value: 0
fov	Horizontal field of view (in fact zoom) Possible values: Math.PI / 2 – Math.PI/20 default value: 1.2
showNavigation	true/false – enables or disables the option to move to neighboring snapshots default value: false
lang	language (used for tooltips, error messages, etc.) Possible values: cs, de, el, en, es, fr, it, nl, pl, pt, ru, sk, tr, uk default value: cs

Return Values

The function returns an IOutput object, which contains the following keys:

Panorama Information
info.lon, info.lat	Information about the actual location of the photographed place
info.date	Date of taking the snapshot in the format YYYY-MM-DD hh:mm:ss
Status Information
errorCode	“NONE” \| “PANORAMA_NOT_FOUND” \| “MISSING_API_KEY”
error	Description of the error
Functions
destroy function	A function that removes the panorama
addListener, removeListener functions	event tracking for panorama view change “pano-view” and panorama place change “pano-place” (see example)
setCamera, getCamera functions	functions for setting/reading the current panorama view

A demo of panoramaFromPosition()


    interface ICreatePanoFromPositionOpts {
        /** Parent element */
        parent: HTMLElement;
        /** Wgs84 longitude coordinate */
        lon: number;
        /** Wgs84 latitude coordinate  */
        lat: number;
        /** API key */
        apiKey: string;
        /** Default pano view - yaw - "auto", "point" - direction to point, number - custom value <0;2 * Math.PI> [rad] */
        yaw?: "auto" | "point" | number;
        /** Default pano view - pitch */
        pitch?: number;
        /** Horizontal field of view */
        fov?: number;
        /** Search area radius [m] */
        radius?: number;
        /** Supported langs: cs, de, el, en, es, fr, it, nl, pl, pt, ru, sk, tr, uk */
        lang?: TLANGS;
        /** Show navigations - neighbors, click mask */
        showNavigation?: boolean;
        /** Hide errors output */
        hideErrors?: boolean;
    }
     
    interface ICreatePanoFromPositionOutput {
        /** Panorama meta information */
        info?: {
            /** Pano wgs84 longitude coordinate */
            lon: number;
            /** Pano wgs84 latitude coordinate */
            lat: number;
            /** Create date YYYY-MM-DD hh:mm:ss*/
            date: string;
        };
        /** Error message */
        error: string;
        /** Error code */
        errorCode: "NONE" | "PANORAMA_NOT_FOUND" | "MISSING_API_KEY" | "WRONG_API_KEY";
        /** Add listener */
        addListener: (name: T, callback: (data: IEvent[T]) => void) => void;
        /** Remove listener */
        removeListener: (name: T, callback: (data: IEvent[T]) => void) => void;
        /** Get panorama camera */
        getCamera: () => ICamera;
        /** Set panorama camera */
        setCamera: (camera: ICamera) => void;
        /** Destroy panorama */
        destroy: () => void;
    }
    interface ICamera {
        yaw: number;
        pitch: number;
        fov: number;
    }

Tracking Rotation and Translation

You can connect to events that are triggered when the view is changed or when the panorama moves to another location.

Example of connecting events panoramaFromPosition()

// add listener - pano view change panoData.addListener("pano-view", viewData => console.log(["view data", viewData])); // add listener - pano change place panoData.addListener("pano-place", placeData => console.log(["place data", placeData]));

Function panoramaExists()

This function checks if a panorama is available at the given location. Input parameters and return values are similar to the panoramaFromPosition() function.

Example of panoramaExists() Interface


  interface IPanoramaExistsOpts {
        /** Wgs84 longitude coordinate */
        lon: number;
        /** Wgs84 latitude coordinate  */
        lat: number;
        /** API key */
        apiKey: string;
        /** Search area radius [m] */
        radius?: number;
    }

    interface IPanoramaExistsOutput {
        /** Panorama meta information */
        info?: {
            /** Pano wgs84 longitude coordinate */
            lon: number;
            /** Pano wgs84 latitude coordinate */
            lat: number;
            /** Create date YYYY-MM-DD hh:mm:ss*/
            date: string;
        };
        /** Panorama exists? */
        exists: boolean;
    }