Background theory


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

    To map coordinates to points on the surface of a sphere, we must establish the reference point — 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 can have a value 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 must 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 cartographical 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.

    It is possible to 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 the 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 area).

    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.


    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, HTML and JavaScript code is generated that is used for displaying maps in a rectangular container. The second case is a normal 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 area

    The region displayed in the viewport is called the mapping area. By definition, it is obvious that it is also rectangular.

    There are three ways to set the mapping area:

    • 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 area is only used in the JavaScript API.

    • Setting the center and zoom level. As demonstrated earlier, the zoom level determines the number of tiles the image of the area is divided into. From this, it is clear that setting the center and zoom level will define the mapping area. This method of setting the mapping area can be used in both the Static API and the JavaScript API.
    • 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 area can be used in both the Static API and the JavaScript API.


    To make the map display convenient and efficient, the map image is divided into squares that are 256x256 pixels in size, 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 — 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 quantity of information. The tile approach is used, for example, in the clusterization 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.