Documentation
Reference
2.1.38 (current version)
collection
interactivityModel
Interfaces

Enabling the API

In order to use the Yandex.Maps API, the API components must be loaded together with the page code, like a normal external JavaScript file. The most common method of enabling external scripts is using the script element in the HTML document header.

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"> </script>
    </head>
</html>

The URL for loading has the format:

https://api-maps.yandex.ru/<version number>/?lang=<language id>&<additional parameters>

Note. The API components can only be loaded over the HTTPS protocol.

For commercial versions of the API, the download link has the format:

https://enterprise.api-maps.yandex.ru/<version number>/?lang=<language id>&apikey=<API key>&<additional parameters>

Version numbering is described in the section API versions.

Note. In the standard browser for the Android mobile operating system and Apple iOS earlier than version 3.2, the zoom gesture causes the zoom of the entire page to increase using the browser resources. To disable processing zoom gestures, add the following code to the page's "head" tag:
<meta name="viewport" content="initial-scale=1.0, user-scalable=no, maximum-scale=1" /> 

For more information, see the description of the "viewport" metatag in the Safari HTML Reference.

API loading parameters

ParameterMandatory parameterDescription

lang

The API lets you display maps that are localized in various languages with allowances for the differences in specific countries. To control localization, pass the locale in the HTTP request.

The locale is set in the lang parameter:

lang=language_region

  • language — The two-letter language code. Specified in ISO 639-1 format. Sets the language for objects on the map (toponyms and controls).
  • region — The two-letter country code. Specified in ISO 3166-1 format. Determines regional settings such as measurement units (for indicating distances between objects or driving speeds on a route).
    Note. For the regions RU, UA, and TR, distance is shown in kilometers. For US, distance is shown in miles.

The following locales are currently supported:

  • lang=tr-TR
  • lang=en-US (distance in miles)
  • lang=en_RU
  • lang=ru-RU
  • lang=ru_UA
  • lang=uk_UA

Note. In early versions of the API, the locale was specified after a dash. This notation is no longer recommended for use, but for backward compatibility, the locales ru-RU, tr-TR, en-US, and uk-UA are considered equivalent to ru_RU, tr_TR, en_US, and uk_UA.
apikey *
[no-highlight[

* Only for commercial versions of the API.

]no-highlight]

API key. Used only in commercial versions of the API. You can get a key in the developer's dashboard.

Note. The key will be activated after the licensing agreement has been confirmed with Yandex.

coordorder

The order for setting geographical coordinates in API functions that accept longitude-latitude input (for example, Placemark).

Possible values:

  • latlong — [latitude, longitude] — used by default.
  • longlat — [longitude, latitude].

Default value: latlong.

load

List of modules to load.

Module names are comma-separated. For example, load=Map,Placemark,map.addon.balloon.

By default, all the API components are loaded (load=package.full), but in order to minimize the traffic sent to the client application, you can set a list of specific API entities that your application uses.

Note. package.full is optimized to load functionality at the time when it is actually used, so in most cases it is not necessary to configure the load parameter.

Components can also be loaded on demand, using the require function.

Default value: package.full.

mode

API loading mode.

The API code can be loaded in packed format to minimize traffic and browser execution time (mode=release), or as source code (mode=debug).

Loading the source code is useful for debugging JavaScript components, since the code of all the loaded components can be viewed. In addition, this mode outputs error messages and exceptions to the console. When the packed format is loaded, these messages are not output.

Default value: release.

ns

The namespace that the API programming components are localized in.

By default, all the objects belong to the ymaps namespace (for example, ymaps.Map). If you specify ns=myNameSpace when loading the API, these objects will be accessible as myNameSpace.Map.

Using a namespace helps avoid crossovers between the names of functions and various programming components used in the API and in user code or other third-party code.

You can set an empty ns value. In this case, the API will not create objects in the global viewport, and access to API functionality will only be given to the function specified in the onload parameter.

Default value: ymaps.

onload

Name of the function that must be called after the API components are loaded and ready to use (callback). The namespace object with API functionality will be passed to this function as an argument.

Nested namespaces may be used:

onload=myfunction

onload=myapp.dosmth

A usage example is provided in the table below.

onerror

The name of the callback function that will be called if an error occurs when loading the API. This function will be passed an object containing information about the error, in the form of an argument.

* Only for commercial versions of the API.

Loading the API on a condition

API components can also be enabled using the modules.require function, which is convenient when loading must depend on certain conditions.

<script src="https://api-maps.yandex.ru/2.1/?load=Map&lang=en_US"type="text/javascript"></script>
<script type="text/javascript">
    var map = new ymaps.Map("map", {
            center: [55.76, 37.64], 
            zoom: 10
        });

    if (map) {
        ymaps.modules.require('Placemark', 'Circle', function (['Placemark', 'Circle']) {
            var placemark = new Placemark([55.37, 35.45]);
        })
    }
</script>

API readiness

Yandex.Map API components are always loaded asynchronously. This is true even if the script tag is used for enabling the API and no other special actions are performed for asynchronous loading.

In order to be sure that the components are loaded and ready for use, use the ready function or the onload loading parameter.

Using the ready() functionUsing the onload loading parameter
<script src="https://...?load=package.standard&lang=en_US"></script>
<script type="text/javascript">
    var myMap;
    ymaps.ready(function () {
        myMap = new ymaps.Map("YMapsID", {
            center: [55.76, 37.64],
            zoom: 10
        });
    ...
    });
</script>

<div id="YMapsID" style="width: 450px; height: 350px;"></div>
// Creating the map's div container
<div id="YMapsID" style="width: 450px; height: 350px;"></div>

<script type="text/javascript">
    var myMap;
    function init (ymaps) {
        myMap = new ymaps.Map("YMapsID", {
            center: [55.87, 37.66],
            zoom: 10
        });
        ...
    }
</script>

// The init function will be called immediately after loading the API.
// When it is executed, the map's div container will already be ready.
<script src="https://...?load=package.standard&lang=en_US&onload=init"><script>

The occurrence of an event for loading the DOM tree or document does not indicate that the API has finished loading. In other words, using event handlers like document.ready, window.onload, jQuery.ready or others does not allow you to determine whether the components are ready for use.

For the map to be initialized, the DOM tree must contain the element that the map is placed in.

The ready function executes its code only after the API components and the document's DOM tree are loaded.

The function passed to the onload parameter is called after the API is loaded, but does not keep track of the DOM tree's readiness. In this case, you must track the availability of the HTML element that the map is placed in. For example, you can use the event handlers that are listed above.

Using the onload parameter lets you initialize the map without waiting for the DOM to be completely formed. This is why this method is the fastest way to load the API.