--- metadata: - name: generator content: Diplodoc Platform v5.39.1 alternate: - https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/dg/concepts/load.md - https://yandex.com/dev/jsapi-v2-1/doc/ru/v2-1/dg/concepts/load.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/jsapi-v2-1/doc/en/llms.txt # 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. For example: ```xml ``` {% note alert %} The API components can only be loaded over the HTTPS protocol. {% endnote %} For free versions of the API, the download link has the format: ```http https://api-maps.yandex.ru/`<`version number`>`/?apikey=Your API key&lang=& ``` For commercial versions of the API, the download link has the format: ```http https://enterprise.api-maps.yandex.ru/`<`version number`>`/?apikey=Your API key&lang=& ``` [More information about API versions](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/versions/index.md). Note that 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: ```xml ``` For more information, see the description of the "viewport" metatag in the [Safari HTML Reference](https://developer.apple.com/library/safari/documentation/appleapplications/reference/safarihtmlref/articles/metatags.html). ## API loading parameters {#param} #| || **Paramete:** | **Mandatory parameter** | **Description** || || **apikey** | ![](../_images/check.png) | API key. You can get a key in the [developer's dashboard](https://developer.tech.yandex.ru/). || || **lang** | ![](../_images/check.png) | 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: ```javascript lang=language_region ``` - `language` — The two-letter language code. Specified in [ISO 639-1](https://ru.wikipedia.org/wiki/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](https://ru.wikipedia.org/wiki/ISO_3166-1) format. Determines regional settings such as measurement units (for indicating distances between objects or driving speeds on a route). {% note info %} For the regions `RU`, `UA`, and `TR`, distance is shown in kilometers. For `US`, distance is shown in miles. {% endnote %} 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 info %} 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`. {% endnote %} || || **suggest_apikey** | | Key [Geosuggest API](https://yandex.com/dev/geosuggest/doc/en/). You can get a key in the [developer's dashboard](https://developer.tech.yandex.ru/). {% include [include](../../../_includes/2.1/terms/index-e50a13eaa8b4.md) %} || || **coordorder** | | The order for setting geographical coordinates in API functions that accept longitude-latitude input (for example, [Placemark](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Placemark.md)). 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`. Components can also be loaded on demand, using the [require](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/modules.require.md) 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`. || || **csp** | | Enables CSP mode. Accepts the value "true". For more information, see [Enabling the API when using CSP](#using-csp). || || **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](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Map.md)). If you specify `ns=myNameSpace` when loading the API, these objects will be accessible as `myNameSpace`.[Map](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/Map.md). 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](#example) 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 {#condition} You can also use the [modules.require](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/modules.require.md) function to enable separate API components, which is convenient when loading must depend on certain conditions. ```xml ``` ## API readiness {#api-ready} 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](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ready.md) function or the [onload](#param_onload) loading parameter. #| || **Using the ready() function** | **Using the onload loading parameter** || || ```php
``` | ```php // Creating the map's div container
// The init function will be called // immediately after loading the API. // When it is executed, the map's // div container will be ready. ``` The loaded modules will be enabled in the public namespace `ymaps`. If additional modules are required for the given modules to work, they will be loaded automatically. The [Sandbox](http://api.yandex.ru/maps/jsbox/2.1/load_modules) has an example of loading modules via the `load` parameter. ### Loading modules on demand {#require} Sometimes a module needs to be loaded on demand. Use the [{#T}modules.require.md]](../../ref/reference/modules.require.md) function for this purpose: ```javascript if (!ymaps.Map) { ymaps.**modules.require**(['Map', 'Placemark'], function (Map, Placemark) { // Adding the class manually to the global viewport, since this doesn't 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 wasn't added to the public viewport. placemark = new Placemark([55.55, 37.00]); map.geoObjects.add(placemark); }) /* The placemark won't be created because the Placemark class isn't included in ymaps. var newPlacemark = new ymaps.Placemark([55.50, 37.00]); */ } ``` Since these modules may require loading additional modules in order to work, the `modules.require` function supports asynchronous mode. When the data needed by the specified modules is ready, it calls the callback function with the loaded modules. The [Sandbox](http://api.yandex.ru/maps/jsbox/2.1/module_request) has an example of loading modules on demand. ### Enabling add-ons {#addons} Displaying a geo object's balloon and hint is performed using the `balloon` and `hint` fields for the [GeoObject](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/GeoObject.md) class. To initialize these fields, you must enable the modules [geoObject.addon.balloon](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/geoObject.addon.balloon.md) and [geoObject.addon.hint](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/geoObject.addon.hint.md). If you need to open a balloon or hint that belongs to the map, you need to enable the [map.addon.balloon](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/map.addon.balloon.md) and [map.addon.hint](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/map.addon.hint.md) modules. If you need to be able to edit a geo object's geometry, you should enable [geoObject.addon.editor](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/geoObject.addon.editor.md). The [Sandbox](http://api.yandex.ru/maps/jsbox/2.1/load_modules) has an example of enabling add-ons. ### Creating custom modules {#define} You can use the API module system to create custom programmatic modules. This is useful when writing large-scale applications based on the Yandex Maps API. The module is declared using the [modules.define](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/modules.define.md) method. The [Sandbox](http://api.yandex.ru/maps/jsbox/2.1/custom_module) has an example of declaring and using a custom module. The module declaration can be made before calling the [ymaps.ready](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/ready.md) handler. After the module has been declared in the module system, it can be used in an application. {% note info %} Custom modules are not added automatically in the general namespace with the API modules. A declared module can be accessed via the asynchronous [modules.require](https://yandex.com/dev/jsapi-v2-1/doc/en/v2-1/ref/reference/modules.require.md) method, which returns a promise object. {% endnote %} ```javascript ymaps.modules.require(['PlacemarkButton']) .spread(function (PlacemarkButton) { myMap.controls.add(new PlacemarkButton('Click to add a placemark')); }); ```