2.1.62 (current version)
2.1.64 (release candidate)

Objects on the map

The Yandex.Maps API lets you place visual objects (geo objects) on maps. When using the JavaScript API, you can put icons with text (placemarks), balloons, popup hints, lines, and polygons on maps, as well as define your own custom visual objects. If you are using the Static API, you can place icons with text, lines, and polygons on a map.


A balloon is a popup window for showing any type of HTML content. It is placed at a point with set coordinates. Only one balloon can be shown on the map at a time. It is only used in the JavaScript API.


A placemark is an image (a normal icon) with content placed in it. However, content is optional. It is placed at a point with set coordinates.

In the JavaScript API, you can use icon images from the built-in collection, and set certain parameters for displaying placemarks. Additionally, you can define your own custom placemark images. The content can be normal text, or can be set using HTML markup.

In the Static API, you can only use placemark icons from the built-in collection. The content can only be positive integers from 1 to 99.

The built-in collections of placemark icons are different in the JavaScript API and the HTTP API.

Figure 1. JavaScript API placemarks

Figure 2. HTTP API placemarks


A polyline (line) is a geometric shape consisting of segments whose endpoints are sequentially connected. The endpoints of segments are called the points of the polyline. If the coordinates of the first and last points on a polyline coincide, the polyline is called a closed polyline.

In the Yandex.Maps API, a polyline is defined by setting a sequence of point coordinates, as well as the color, transparency, and thickness of the line that connects the points.


A polygon is a geometric shape consisting of a section of a plane bound by a closed polyline.

A polygon includes both the polyline points and all the points inside its area, as well. This means that besides the parameters of the polyline that borders the polygon, two additional parameters are introduced: fill color and transparency for the inside area.


A circle is a geometric shape consisting of a section of a plane bound by a ring.

A circle is set using two parameters: the center and radius.

A circle includes both the points on the ring and all the points inside its area, as well. In the same way as for a polygon, color and transparency can be set both for the ring outline and for the fill of the inside area.

Popup hint

A popup hint is a window that can display text or HTML content. It is contained by a point with set pixel coordinates. Since the hint is a pseudo-overlay, it is not bound to coordinates itself. So if the hint is put in a point in the viewport, it will not change positions when the map is moved or the zoom level changes.

You can change the appearance of the hint window's content as you wish. Only one hint can be shown at a time on a map.

It is only used in the JavaScript API.

Placing geo objects on a map

The section Coordinates describes how the Yandex.Maps API lets you work with geographical coordinates that are unrestricted by longitude, which lets you project the surface of the Earth onto multiple worlds. Considering these factors, let's examine how overlays are added.

Geo objects with coordinates that are defined by normal geopoints are always shown in the world that is closest to the center of the map viewport. This means that when the map center moves, these objects can "jump" to the neighboring world in order to be closer to the center.

Moving a point object to a neighboring world can be interpreted as if this object is rotating around the surface of the Earth. Using unrestricted geopoints lets you turn the Earth to the East or West as many times as necessary. For example, you can create a polyline that demonstrates a flight trajectory from Ankara to Istanbul via Canada. The same polyline can be created using restricted geopoints, as well.

The Yandex.Maps API uses the following rules. A line between two points is always drawn with the shortest possible length. So if the difference between the longitude of the first and second points is more than 180 degrees, they will be connected by a short trajectory. However, if an intermediate point is used to connect the two points, and it is no more than 180 degrees away from them, the points can be connected by a long trajectory.

This means that it is possible to use geo objects that are located in multiple worlds simultaneously, using normal geopoints. Taking into account what was described above, these geo objects will "jump" between locations if the map in the viewport is shifted significantly.

Geo objects that are defined using a single coordinate pair (placemarks and balloons) will jump when the map is moved and the world they are located in turns out to be further away from the center of the viewport than the neighboring world. For geo objects that are defined by multiple coordinate pairs (lines and polygons), the jump will occur when their left or right end point (corner) is far enough away from the center. Additionally, the shift will happen for as many worlds as the geo object is located in.