General information

The Yandex API JavaScript API is a set of JavaScript components for publishing interactive maps on web pages.

The API components are implemented as classes, functions, static objects, and interfaces.

The API uses the following naming convention: all class names start with a capital letter (Map, Balloon), and classes that define interfaces start with the capital letter «I» (IGeoObject). All other object names start with a lowercase letter.

Namespace

All the API components belong to a single namespace (by default, it is «ymaps»). The components can be logically grouped in second-level or third-level namespaces, such as ymaps.map.Hint, or ymaps.map.Balloon.

The namespace can be changed when loading the API, using the ns parameter (for example, ns=myNameSpace).

Using a global namespace helps avoid «crossovers» between the names of Yandex Maps API components and user code or third-party libraries.

Layout

When an interactive map is being generated, the HTML code is generated dynamically and embedded in the DOM tree for the page the map is published on.

Where appropriate, instead of standard HTML elements such as img and div, the generated code uses a ymaps element instead. In addition, all styles in the code generated by the API are based on CSS classes that have the “ymaps-” prefix, and the API's CSS only uses selectors from these classes. This minimizes the likelihood of a layout conflict. As long as the user's HTML code does not use the ymaps element, and the user's CSS definitions do not contain classes with the “ymaps-” prefix, there will not be any layout conflicts. In other words, the user's CSS will not affect the way the map and its elements are displayed, and the API's CSS will not affect the user's layout.

Map objects

Hierarchy of map objects

The root element in the API's object hierarchy is the map.

The map has four global collections: the geo objects collection, the controls collection, the layers collection, and the [behaviors](*behavior) collection. The map only displays objects that were added to these global collections (in other words, objects can be added to a map only by adding them to the global collections). In the same way, to remove objects from a map, they must be deleted from the global collections:

myMap.geoObjects.add(myGeoObject) — Adding an object to the map.

myMap.geoObjects.remove(myGeoObject) — Removing an object from the map.

Before adding objects to global collections, they can be grouped in ICollection collections. For example, a placemark (Placemark) can be added to the GeoObjectCollection collection and then this collection can be added to the global collection of map geo objects. Then the placemark will be displayed on the map. An exception is behaviors, which are always immediately added to the global collection of map behaviors and are not grouped in lower-level collections.

The map also has two separate entities, the balloon and hint, which do not belong to global collections. Only one balloon (hint) can be added to a map.

Options, data, and states

Among the properties of the API programming components, the most significant are options, data, and state, which are usually designated as options, data or properties, and state, respectively.

For example, constructors for the Hint and control.TrafficControl classes look like this:

Hint (map, data, options)
control.TrafficControl (state)

Options are responsible for the visual appearance of objects (for example, a placemark icon, or the outline thickness and color for a polyline or polygon). Options can take strictly defined values.

The information in data (or properties) is custom data that contains any information about an object (for example, its name, the text of a balloon and hint, the length of a route or traveling time). Data may contain any fields.

State describes the object properties that can be changed using the visual interface (for example, whether a button is selected or deselected).

Options, data and state are all presented as a JavaScript object consisting of a set of «key:value» pairs.

Description

Example

When the mouse cursor hovers over a placemark, a popup hint is shown with the content hintContent.

When the placemark is clicked, a balloon opens with the content balloonContent.

var data = {
        balloonContent: 'Hello Yandex!',
        hintContent: 'Placemark',
      iconContent: '1'
    },
    options = {
      balloonHasCloseButton: true
    },
    myPlacemark = new ymaps.Placemark([48, 40], data, options);

// Adding an object to the map
myMap.geoObjects.add(myPlacemark);

Options inheritance

For options, hierarchical inheritance is implemented. This means that a programming object recursively inherits options from its parents, although in any case it only interprets part of them.

The top-level item in this hierarchy is the map. Using the map, you can set options for the map itself, as well as for all the objects related to it: geo objects, controls, layers, their collections, and so on. For example, the map options can be used to set the icon for displaying a placemark, and this icon will be used by default for all placemarks that are placed on the map.

When setting object options without using the map, the scope of these options narrows. For example, if you set a balloon option via the GeoObjectCollection collection of geo objects and open the balloon via an instance of a map class (myMap.[balloon](../../ref/reference/Map.md#balloon).open()), the option will not be applied.

The API implements support for preset options, known as presets.

There is special storage for presets option.presetStorage, which allows for assigning a named key to a preset. The storage is a static object that already contains presets, which can be used (or are being used) by certain API components.

To use the values defined in a preset, when setting an option, refer to the preset ID from this storage using the preset key.

Description

Example

Placemark with a white icon that stretches to fit the content

var myPlacemark = new ymaps.Placemark(
    [55.7, 37.6],
    { iconContent: 'Use presets' },
      // The icon will be green and stretch to fit iconContent
      { **preset: 'islands#greenStretchyIcon'** }
    );

Using this method, you can only refer to a single preset.

Presets are nothing more than a convenient way to set a group of options. For options that are set using presets, the standard inheritance hierarchy is used.

You can find a list of available presets in the Reference guide.

Before an object is displayed on the map, the API first attempts to determine which options were explicitly set for the object. If there aren't any, the API looks for presets defined for the object. If presets weren't defined, options are searched for moving up the hierarchical tree to the map level.

The priority option for an object is the option that is set for it explicitly. If the same option is set on different levels for an object, the option will be applied that is set on a lower level.

// Setting placemark options via the map
myMap.options.set({
    geoObjectZIndexHover: 200 // z-index of a geo object when pointing at it with the mouse
})

//  Setting options for a placemark directly, via the Placemark object
myMap.Placemark.options.set({
  zIndexHover: 100 // for this placemark, the option value is 100
})

Using prefixes in option names

There are many objects in the API that can have options with identical purposes set for them (for example, the map balloon layout and the geo object balloon layout). To differentiate between such options, we could have explicitly defined their names for the entire API. However, this would have led to a huge list of options with long names.

So to differentiate options with identical purposes, prefixes are used in the names of these options (for example, _balloon_Layout or _icon_Layout).

When setting options for map child objects on the map level (that is, via the map itself), prefixes must always be used. When moving down the hierarchical tree, at each level, part of the corresponding prefixes is discarded. Prefixes are not used when setting options explicitly for an object via this object.

Examples are shown below for using prefixes for layout options when setting the layout for particular objects (placemarks, balloons, hints, and clusters).

For setting an object's layout explicitly via this object (for example, the map hint), the layout option is specified without a prefix:

myMap.hint.open([56, 37], {'I'm a hint'}, {
  layout: MyHintLayoutClass // map hint layout
});

When setting options for certain objects via their collections (i.e., one level higher), the appropriate prefixes must be specified: icon, balloon, hint and so on:

// Setting geo object layouts via their collections
myGeoObjectCollection.options.set({
    hintLayout: MyHintLayoutClass // hint layout for all geo objects from this collection
    balloonLayout: MyBalloonLayoutClass // balloon layout for all geo objects from this collection
    iconLayout: MyIconLayoutClass // icon layout for all geo objects from this collection
    ...
});

Via the clusterer you can set options for placemarks and clusters that are in it, as well as for their balloons and hints. Cluster options are set using the “cluster” prefix, while options for placemarks in the clusterer are set using the “geoObject” prefix.

// Setting options for placemarks and clusters via the clusterer
myClusterer.options.set({
    clusterIconLayout: MyIconLayoutClass // icon layout for clusters in the clusterer
    geoObjectIconLayout: ... // icon layout for clusterer placemarks
    geoObjectBalloonContent: ... // balloon content for placemarks in the clusterer 
    ...
});

When setting options for objects via global collections, similar prefixes are specified:

myMap.geoObjects.options.set({
    iconLayout: MyIconLayoutClass, // icon layout for all map objects
    balloonLayout: MyBalloonLayoutClass, // balloon layout for all map objects
    clusterBalloonLayout: ... // balloon layout for clusters
    ...
});

When setting options for geo objects, the balloon, and the hint via the map (that is, at the uppermost level), in addition to the prefix that corresponds to the particular object (icon, balloon, and so on), you must also add the geoObject prefix:

// Setting object options via the global collection for geo objects
myMap.options.set({
    geoObjectIconLayout: MyIconLayoutClass, // layout for all placemarks on the map
    geoObjectBalloonLayout: MyBalloonLayoutClass, // layout for map geo object balloons
    balloonLayout: ... // layout for all map balloons
    geoObjectClusterBalloonLayout: ... // layout for cluster balloons
    ...
});