Background theory

When using the Yandex Maps API, it is most convenient to represent a map as an image of a location or object with each point mapped to a coordinate pair.

The map is made up of one or more layers that are layered over each other, with each layer divided into multiple square sections called tiles. When the map is displayed, all tiles are combined, layers are layered over each other, and a single image is created. Generation of a single image is performed automatically and this process is hidden from the user.

You need to understand the mechanism for generating an image, perhaps, only when creating your own map. Most users who use standard sets of Yandex Maps just need to conceive the map as suggested in the first paragraph.


Geodetic systems


The map in the browser

Map viewport

Mapping region



The location of a point on the map can be described using certain coordinates. If we are talking about a map of the surface of the Earth, spherical coordinates, latitude and longitude, are usually used.

To map coordinates to points on the surface of a sphere, we should establish the reference point, that is, the fundamental plane for determining latitudes, and the prime meridian for calculating longitudes. For the Earth, the equatorial plane and the Greenwich meridian are typically used.

Latitude (usually denoted by φ) is the angle between the equatorial plane and the radius from the center of the sphere to a particular point. Longitude (usually denoted by θ or λ) is the angle between a plane containing the prime meridian and a plane containing the meridian that runs through the point in question.

Longitude ranges from -180 to 180 degrees, and latitude ranges from -90 to 90 degrees.

Geodetic systems

Since the Earth is not a sphere, additional rules are necessary in order to map a coordinate pair to each point on the Earth's surface. These rules are defined by a geodetic system.

Currently, the majority of geographic services (including Yandex Maps) use the WGS 84 system, in which the Earth is considered to be an ellipsoid with an equatorial radius of 6378.137 km and a polar radius of 6356.752 km.


In order to display a map of the world on a plane, a projection of the image should be created somehow. Yandex Maps, like most other geoinformational services, uses the Mercator projection.

Note that the Mercator projection distorts the shape and size of objects; the closer an object is to a pole, the more space it takes up on the map. For example, Greenland looks bigger than Australia, while in reality, Australia is 3.5 times larger than Greenland.

In contrast to certain other cartographic services, Yandex Maps uses the elliptical Mercator projection (complying with WGS 84), rather than the spherical projection. This is why a Yandex map will not match up with maps that use the spherical Mercator projection.

You can work with Yandex Maps via the API in both projections (see ymaps.projection.wgs84Mercator and ymaps.projection.sphericalMercator).

Cartesian coordinates

It does not always make sense to use geographical coordinates. For example, it is difficult to imagine using longitude and latitude for setting coordinate points on the plan of an office building. For this task, it makes more sense to use the well-known and familiar Cartesian (rectangular) coordinate system. The Yandex Maps API supports Cartesian coordinates (see ymaps.projection.Cartesian).

Custom coordinates

The Yandex Maps API can display maps that are created in any projection and handle any coordinates. You only need to set rules for the map to convert point coordinates to pixel coordinates (see the next section) and back. A custom map can be connected along any axis or even along two axes at once.

The map in the browser

As a result of projection, we get an image of a geographic map on an endless pixel plane. The map in the browser shows a small part of this plane (the so-called mapping region).

To make it convenient to work with the map, we use the concept of zoom level. At the zero zoom level, the entire «world» is displayed on an area that is 256x256 pixels in size. When increasing the zoom by one level, the dimensions of the «world» double, which means that for zoom level z, the dimensions are 2z+8x2z+8 pixels.

This is how each point on the map is described by its pixel coordinates and zoom level. The reference point for pixel coordinates is located in the upper-left corner of the map. If we know the map projection, we can easily convert geographical coordinates to pixel coordinates and back.

Map viewport

The Yandex Maps API lets you generate two types of maps: interactive (using the JavaScript API) and static (using the Static API). In the first case, an HTML and JavaScript code is generated to display maps in a rectangular container. The second case is a regular image that has a rectangular shape. The rectangular area in the browser window that contains the image of part of an area is called the map viewport.

The div element is usually used for interactive maps, and the img element for static maps. The location and size of the map viewport is determined by the parameters of these HTML elements.

Mapping region

The area displayed in the viewport is called the mapping region. It is clear from the definition that it is also rectangular.

There are three ways to set the mapping region:

  • Setting boundaries. To effectively set the boundaries of the rectangle, you only need to set the coordinates of two of its corners that are diagonal to each other. In the Yandex Maps API, the coordinates of the lower-left and upper-right corners are used.

    This method of setting the mapping region is only used in the JavaScript API.

  • Setting the center and zoom level. The zoom level determines the number of tiles the image of the area is divided into.

  • Setting the center and the range by longitude and latitude. The range by longitude and latitude is set in degrees. This method of setting the mapping region can be used in both the Static API and JavaScript API.


To make the map display convenient and efficient, the map image is divided into squares that are 256x256 pixels in size. They are called tiles. When generating the image in the browser, the API loads only the tiles that are visible right now, which helps limit traffic and use caching efficiently.

At the smallest scale (zoom level 0), the entire territory is covered by a single tile.

At the next scale level (zoom level 1), the entire territory is made up of four tiles.

At a more detailed scale (zoom level 2), the entire surface of the Earth is covered by a grid of 16 tiles (4x4), and so on.

This means that each zoom level divides the map into 4N tiles, where N is the zoom level.

Tiles are usually labeled in the same way as pixel coordinates, that is, starting from the upper-left corner of the "world". To get a tile number, divide the global pixel coordinates of its upper-left corner by 256 and round down.

Dividing the map into sections like this is useful not only for displaying the base layer itself, but also for services that provide a significant volume of information. The tile approach is used, for example, in the clustering and hotspot layers technologies. In addition, the Yandex Maps API supports any mechanisms for dividing surfaces into sections, not necessarily as equal squares; you only need to set the rules for converting tile numbers to global pixels and back.