Documentation
Reference
2.1.56 (current version)
collection
interactivityModel
Interfaces

Overview

The Yandex.API JavaScript API is a set of JavaScript components for creating interactive maps. The components are placed on Yandex servers and are available for use as soon as they are uploaded to the page.

Enabling the API

The API is enabled in a standard way by uploading an external JavaScript file containing the API components.

Attention! The API is accessed over the HTTPS protocol.

<head>
...
    <script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"></script>
...
</head>

You can load all the API components, or separate modules. This allows you to control the volume of traffic passed to the client application.

<script src="https://api-maps.yandex.ru/2.1/?lang=en_US&load=Map" type="text/javascript"></script>

In the first example, all the API components were enabled. In the second one, the Map module was enabled, containing only the functionality for showing the map itself. The set of modules to load is set in the load parameter.

In addition, the API supports loading components “on demand”, meaning they can be loaded at the time when they are needed.

<script src="https://api-maps.yandex.ru/2.1/?lang=en_US&load=Placemark" type="text/javascript"></script>
<script type="text/javascript">
  if (!ymaps.Map) {
    ymaps.modules.require('Map, Placemark', function (Map, Placemark) {
         // Adding a class manually to the global viewport, since this does not happen when using the module system's "require" method.
        ymaps.Map = Map;
        var map = new ymaps.Map('map', { 
              center: [55.76, 37.64], 
              zoom: 10    
            }),
            // The Placemark class was not added to the public viewport.
            placemark = new Placemark([55.55, 37.00]);
        map.geoObjects.add(placemark);
    })
    /* The placemark will not be created, because the Placemark class is not included in ymaps.
    var newPlacemark = new ymaps.Placemark([55.50, 37.00]); 
    */
}
</script>

In the example, the module containing the functionality for working with the map will be loaded by the modules.require function.

By default, all the JavaScript API components belong to the ymaps namespace. You can change the namespace using the ns parameter.

<script src="https://api-maps.yandex.ru/2.1/?lang=en_US&load=Map&ns=myNamespace" type="text/javascript">

If you set an empty string for the ns parameter, the API functionality will not be in the public viewport at all, and will be passed as an argument to the specified handler function:

<script>
  function myFunction (ymaps) {
    var myMap = new ymaps.Map({
          center: [55.733835, 37.588227],
          zoom: 4
        });
  }
</script>
<script src="https://api-maps.yandex.ru/2.1/?lang=en_US&ns=&onload=myFunction" type="text/javascript">

Map

The main component of the API is the map, which can be placed in any HTML block element and always has a rectangular shape.

The main map parameters are the viewport, the mapping region, and the map type. When creating a map, you must specify the mapping region (the map center and zoom level). The viewport is defined by the parameters of the HTML element that it is placed in (the map completely fills this element).

<head>
<script type="text/javascript">
  var myMap = new ymaps.Map('myMap', {
        // the center and zoom level explicitly
        // define the mapping region
     center: [39.889847, 32.810152],
     zoom: 7
      });
</script>
</head>
<body>
  <!-- Map viewport -->
  <div id="myMap" style="width: 600px; height: 300px"></div>
</body>

The API provides three built-in map types: map (roadmap), satellite, and hybrid. The map type is produced by layering one or more layers over each other. It is possible to define a new map type by creating custom layers and/or combining the built-in layers. If a map is created without defining the type (as in the previous example), the “map” type is used.

<script type="text/javascript">
  var myMap = new ymaps.Map('myMap', {
        center: [39.889847, 32.810152],
        zoom: 7,
    // built-in "satellite" map type.
    type: 'yandex#satellite'
  });
</script>

Texts on the map can be displayed in various languages. When enabling the API, the language for texts is set by the lang parameter, which is passed the locale in the format <language>_<region> according to the RFC-3066 standard.

<head>
...
  <script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"></script>
...
</head>

The map has a set of behaviors that define the map's response to user actions. For example, when the mouse cursor is moved inside the viewport with the left button held down, the map reacts by changing the mapping area (the image of the location moves to follow the cursor).

When the map is initialized, it is assigned a set of behaviors that can be changed by adding or removing specific behaviors.

var myMap = new ymaps.Map('myMap', {
     center: [39.889847, 32.810152],
     zoom: 10,
     behaviors: ['ruler', 'scrollZoom'],
   });
// Disabling dragging the map with the mouse.
myMap.behaviors.disable('ruler');

The API includes a built-in set of behaviors and offers the possibility of defining your own custom behaviors.

Objects on the map

Any number of geo objects can be placed on the map; these are programming components describing geographical objects in the real world. A geo object is characterized by its geometry, which is defined by its geometric type (point, polygon, and others) and the coordinates of the geographical object.

var myGeoObject = new ymaps.GeoObject({
  // Geometry type - point.
  type: 'Point',
      // Point coordinates.
      coordinates: [39.889847, 32.810152]
    });
myMap.geoObjects.add(myGeoObject);

For each geometry type, an auxiliary class is defined that allows using abbreviated syntax for creating a geo object.

// Corresponds to a geo object with the "point" geometry type (type: "Point")
var myPlacemark = new  ymaps.Placemark([39.889847, 32.810152]);
myMap.geoObjects.add(myPlacemark);

Geo objects can be combined in collections, which lets you define properties for all of their members at once and perform group operations with them.

var myCollection = new ymaps.GeoObjectCollection ({},
  // All objects in the collection can be dragged with the mouse.
  {geoObjectDraggable: true}
);
myCollection.add(myGeoObject);
myCollection.add(myPlacemark);
myMap.geoObjects.add(myCollection);

ymaps.geocode('Kabasakal Caddesi').then(
  // The geocoder returns results as an ordered collection GeoObjectCollection
  function (res) {
    // First result
    map.geoObjects.add (res.geoObjects.get(0));
  }
)

In addition to collections, there is also a special clusterer object that allows grouping geo objects in clusters. This is usually used when geo object markers stack on top of each other at certain zoom levels. In this case, it is more convenient to use a single cluster marker in place of a set of placemarks. When the zoom is increased, the cluster visually separates into individual markers and/or other clusters.

Besides geo objects, the map can display balloons (popup windows), hints, and controls.

The map has a single balloon and a single hint, which are each placed at a point with the specified coordinates.

myMap.hint.open(myMap.getCenter(), 'Map center');

Geo objects have access to the map's balloon and hint, meaning the balloon (hint) may be automatically placed over the geo object without directly setting the coordinates of the balloon (hint).

var myPlacemark = new ymaps.Placemark([48, 40], {balloonContent: 'My <strong>balloon</strong>'});
myPlacemark.balloon.open();

Controls are objects associated with the map and intended for interaction with users. Controls are usually placed in the map viewport. The Maps API includes several sets of controls designed for maps of different sizes, as well as the ability to make your own set or implement your own controls.

By default, the map shows the following controls: search on the map, map type selection, zoom slider, geolocation, full-screen mode, ruler, and the Traffic button. Controls are automatically adapted to the size of the screen.

// Zoom slider
myMap.controls.add('zoomControl', {
    float: 'none',
    position: { left: 10, top: 44 }
});

// Map type selection
map.controls.add(new ymaps.control.TypeSelector());

Coordinates

The base coordinate system of the JavaScript API is the global pixel coordinate system. In this system, every point in the real world is projected on an infinite pixel plane. At the beginning (zero) zoom level, the map of the world fits into an area that is 256 x 256 pixels. When increasing the zoom by one size, the "world map" doubles.

Any coordinate system is implemented using a projection. The projection establishes the correlation between the geographic coordinates of a point and the global pixel coordinates for each zoom level.

The API includes built-in support for standard geographic coordinates and the Cartesian system. For geographic coordinates, the API provides two projections: elliptical (conforming to WGS-84) and the spherical Mercator projection. The first is used in the Yandex.Maps API by default, and the second is often applied in third-party geo services.

When creating a map, it is assigned a projection, which cannot be changed later. The coordinates of all objects on the map are recalculated in global pixel coordinates according to this projecting.

Geographic coordinates can be specified in the format [latitude, longitude], or in the reverse order [longitude, latitude]. The order is set by the coordorder parameter when enabling the API.

<script src="https://api-maps.yandex.ru/2.1/?coordorder=longlat&..." type="text/javascript"></script>

If this parameter is omitted, geographic coordinates are interpreted as if they are set in the format [latitude, longitude], which corresponds to the latlong value for the coordorder parameter.