Документация
Справочник JavaScript API
2.1.55 (текущая версия)
collection
interactivityModel
Интерфейсы

Подключение API

Для использования API Яндекс.Карт необходимо, чтобы компоненты API были загружены вместе с кодом страницы как обычный внешний JavaScript-файл. Наиболее распространенным способом подключения внешних скриптов является использование элемента script в заголовке HTML-документа. Например:

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

Внимание! Компоненты API могут быть загружены только по протоколу HTTPS.

Для бесплатных версий API ссылка для загрузки имеет вид:

https://api-maps.yandex.ru/<номер версии>/?lang=<идентификатор языка>&<дополнительные параметры>

Для коммерческих версий API ссылка для загрузки имеет вид:

https://enterprise.api-maps.yandex.ru/<номер версии>/?lang=<идентификатор языка>&apikey=<API-ключ>&<дополнительные параметры>

Обратите внимание, что в стандартном браузере мобильной операционной системы Android и Apple iOS версии ниже 3.2 жест масштабирования над картой приводит к увеличению масштаба всей страницы средствами браузера. Для того чтобы отключить обработку жеста масштабирования, необходимо добавить в тег head страницы следующий код:

<meta name="viewport" content="initial-scale=1.0, user-scalable=no, maximum-scale=1" /> 

Подробнее см. описание метатега viewport в Safari HTML Reference.

Параметры загрузки API

ПараметрОбязательный параметрОписание

lang

API позволяет отображать карты, локализованные на различных языках с учётом специфики отдельных стран. Для того чтобы управлять локализацией, необходимо в HTTP-запросе передать локаль.

Локаль задается параметром lang:

lang=language_region

  • language — двузначный код языка. Указывается в формате ISO 639-1. Задает язык объектов на карте (топонимов, элементов управления).
  • region — двузначный код страны. Указывается в формате ISO 3166-1. Определяет региональные особенности, например единицу измерения (для обозначения расстояния между объектами или скорости движения по маршруту).
    Примечание. Для регионов RU, UA и TR расстояние показывается в километрах, для US — в милях.

На данный момент поддерживаются следующие локали:

  • lang=ru_RU;
  • lang=en_US;
  • lang=en_RU;
  • lang=ru_UA;
  • lang=uk_UA;
  • lang=tr_TR.

Примечание. В ранних версиях API локаль указывалась через дефис. Данное обозначение более не рекомендуется к использованию, однако, в целях сохранения обратной совместимости локали ru-RU, tr-TR, en-US и uk-UA считаются эквивалентными ru_RU, tr_TR, en_US, uk_UA соответственно.
apikey *
[no-highlight[

* Только для платных версий API.

]no-highlight]

API-ключ. Используется только в платных версиях API. Получить ключ можно в кабинете разработчика.

Примечание. Ключ будет активирован только после заключения лицензионного договора с Яндексом.

coordorder

Порядок задания географических координат в функциях API, принимающих на вход пары долгота-широта (например, Placemark).

Возможные значения:

  • latlong — [широта, долгота] — используется по умолчанию;
  • longlat — [долгота, широта].

Значение по умолчанию: latlong.

load

Список загружаемых модулей.

Имена модулей перечисляются через запятую. Например, load=Map,Placemark,map.addon.balloon.

По умолчанию загружаются все компоненты API (load=package.full), однако в целях минимизации объема трафика, передаваемого клиентскому приложению, вы можете указать список конкретных сущностей API, с которыми работает ваше приложение.

Примечание. package.full оптимизирован таким образом, чтобы подгружать функциональность в момент ее фактического использования, поэтому в большинстве случаев нет необходимости настраивать параметр load.

Компоненты также можно загружать «по требованию», используя функцию require.

Значение по умолчанию: package.full.

mode

Режим загрузки API.

Код API может быть загружен в упакованном виде для минимизации трафика и скорости исполнения в браузере (mode=release), а также в виде исходного кода (mode=debug).

Загрузка в виде исходного кода удобна для отладки JavaScript-компонентов — код всех загруженных компонентов доступен для просмотра. Кроме того, в этом режиме в консоль выводятся сообщения об ошибках и исключениях. При загрузке в упакованном виде эти сообщения не выводятся.

Значение по умолчанию: release.

csp

Включает режим использования CSP. Может принимать значение true. Подробнее см. Подключение API при использовании CSP.

ns

Пространство имен, в котором локализованы программные компоненты API.

По умолчанию все объекты принадлежат пространству имен ymaps (например, ymaps.Map). Если при загрузке API указать ns=myNameSpace, то объекты будут доступны уже как myNameSpace.Map.

Использование пространства имен позволяет избежать пересечения названий функций и прочих программных компонентов, используемых в API и пользовательском/стороннем коде.

Вы можете задать пустое значение ns. В этом случае API не будет создавать объектов в глобальной области видимости, и доступ к функциональности API получит только функция, указанная в параметре onload.

Значение по умолчанию: ymaps.

onload

Имя функции, которую необходимо вызвать после того, как компоненты API будут загружены и готовы к использованию (callback). В эту функцию в качестве аргумента будет передан объект-неймспейс с функциональностью API.

Допускается использование вложенных пространств имён:

onload=myfunction

onload=myapp.dosmth

Пример использования приведен в таблице ниже.

onerror

Имя callback-функции, которая будет вызвана в случае ошибки загрузки API. В эту функцию в качестве аргумента будет передан объект, содержащий информацию об ошибке.

* Только для платных версий API.

Загрузка API по условию

Отдельные компоненты API также можно подключать с помощью функции modules.require, которую удобно использовать в том случае, если загрузку необходимо производить в соответствии с какими-то условиями.

<script src="https://api-maps.yandex.ru/2.1/?load=Map&lang=ru_RU"
 type="text/javascript"></script>
<script type="text/javascript">
  ymaps.ready(function () {  
    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

Компоненты API Яндекс.Карт всегда загружаются асинхронно. Это происходит даже в том случае, если для подключения API используется тег <script> и никаких специальных действий для асинхронной загрузки не производилось.

Чтобы быть уверенным, что компоненты загружены и готовы к использованию, необходимо использовать функцию ready или параметр загрузки onload.

Использование функции ready()Использование параметра загрузки onload
<script src="https://...?load=package.full&lang=ru_RU"></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>
// Формируем div-контейнер карты
<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>

// Сразу после загрузки API будет 
// вызвана функция init.
// На момент ее исполнения div-контейнер 
// карты уже будет готов.
<script src="https://...?load=package.full&lang=ru_RU&onload=init"><script>

Возникновение событий загрузки DOM-дерева или документа не сигнализирует об окончании загрузки API. То есть использование обработчиков событий типа document.ready, window.onload, jQuery.ready и пр. не позволяет определить, готовы ли компоненты для использования.

Для инициализации карты необходимо, чтобы в DOM-дереве находился элемент, в котором она размещается.

Функция ready исполняет включенный в нее код после того, как будет загружены компоненты API и DOM-дерево документа.

Функция, переданная в параметр onload вызывается после загрузки API, но не отслеживает готовность DOM-дерева. В этом случае отслеживать доступность HTML-элемента, в который помещается карта, необходимо самостоятельно. Например, при помощи обработчиков событий, перечисленных выше.

Использование параметра onload дает возможность инициализировать карту, не дожидаясь, пока DOM будет сформирован полностью. Поэтому данный способ является самым быстрым способом загрузки API.

Подключение API при использовании CSP

Если приложение использует политику защиты контента (CSP), то для корректной работы с API в политику необходимо добавить правила, разрешающие загрузку ресурсов с доменов Яндекса.

Внимание! По умолчанию в API отключена поддержка CSP. Для ее активации при подключении API нужно передать параметр csp=true:
https://api-maps.yandex.ru/2.1/?lang=ru_RU&csp=true

В таблице ниже приведены правила, которые необходимо добавить в политику приложения для работы c API. Правила перечисляются отдельно для каждой директивы. Обратите внимание на многоточия в примерах — это означает, что правила, необходимые для работы с API, приведены без учета других правил, которые разработчик может задать для своего приложения. Если для какой-либо директивы в политике будет разрешена загрузка из любых источников (например, 'img-src *;'), то для этой директивы соответствующие правила API можно не задавать.

ДирективаПравила, которые требуется добавить в директиву

img-src

Для директивы img-src в список разрешенных источников необходимо добавить домены:

  • https://*.maps.yandex.net
  • https://yandex.ru

С этих доменов будут загружаться изображения API (например, тайлы). Кроме того, некоторые изображения API вставляются через data:URL, поэтому в директиве img-src также необходимо указать протокол data:.

img-src data: https://*.maps.yandex.net https://yandex.ru ...;

frame-src

В директиве frame-src должен быть разрешен домен

https://api-maps.yandex.ru.

С этого домена будут загружаться компоненты API, которые размещаются во фреймах (например, блок «Открыть в Яндекс.Картах»):

frame-src https://api-maps.yandex.ru ...;

Примечание. Директива frame-src используется в CSP версии 1.0; в версии 2.0 эта директива заменена на child-src. Однако некоторые браузеры еще не поддерживают CSP 2.0, поэтому для обеспечения кроссбраузерной совместимости в политике рекомендуется указывать обе эти директивы:
frame-src https://api-maps.yandex.ru ...;
child-src https://api-maps.yandex.ru ...;

script-src

В директиве script-src нужно указать следующие домены:

  • https://api-maps.yandex.ru
  • https://suggest-maps.yandex.ru
  • https://*.maps.yandex.net
  • https://yandex.ru

С этих доменов будут загружаться модули API. Кроме того, для работы с шаблонами в директиве script-src рекомендуется включить поддержку 'unsafe-eval’ (это необходимо для работы условных операторов).

script-src 'unsafe-eval' https://api-maps.yandex.ru https://suggest-maps.yandex.ru https://*.maps.yandex.net https://yandex.ru ...;

style-src

Для загрузки стилей API в директиве style-src необходимо указать протокол blob:.

style-src: blob: ...;

API будет подключать стили на страницу через элемент <link>, содержащий blob URL нужного стиля. Если в приложении использование blob невозможно, то для корректной работы с API в директиве style-src можно указать nonce-значение, сгенерированное на стороне клиента. В этом случае API будет подключать стили через inline-элемент <style nonce="...">.

style-src 'nonce-<токен>' ...;

Это же значение следует передать в параметре csp при подключении API:

https://api-maps.yandex.ru/2.1/?lang=ru_RU&csp[style_nonce]=<токен>

Следует иметь в виду, что атрибут nonce реализован в CSP 2.0 и не поддерживается в версии 1.0. Однако в некоторых браузерах еще не включена поддержка CSP 2.0, поэтому для обеспечения кроссбраузерной совместимости в style-src рекомендуется использовать протокол blob:.

Если для какого-либо ресурса API политика определена неправильно, то карта (либо ее объекты) будут отображаться некорректно. При этом API не отслеживает, для каких ресурсов политика задана неверно. Чтобы получить информацию о том, какие ресурсы карты не могут быть загружены, можно воспользоваться директивой report-uri.

Ниже приведен пример политики, в которой определены правила для работы с API, а также другие правила приложения:

Content-Security-Policy: img-src data: https://*.maps.yandex.net https://yandex.ru
'self'; child-src https://api-maps.yandex.ru; frame-src https://api-maps.yandex.ru;
 script-src 'unsafe-eval' https://api-maps.yandex.ru https://suggest-maps.yandex.ru
 http://*.maps.yandex.net https://yandex.ru 'self'; style-src blob:
 https://cdn.my-styles.ru;

Задание inline-стилей в шаблонах при включенном CSP

Иногда при работе с шаблонами для DOM-элементов необходимо задавать inline-стили (например, при настройке автопозиционирования балуна). Если в API отключен режим CSP, inline-стили задаются стандартным образом, как обычный HTML-текст. Например:

<div style="width: {{options.width}}px;></div>

Однако при включении режима CSP, если в политике установлен запрет на 'unsafe-inline', данная форма записи работать не будет. Чтобы обойти запрет на использование inline-стилей в шаблонах, можно воспользоваться одним из следующих способов:

  1. Задавать inline-стили через конструкцию {% style %}:

    <div {% style %}width: {{ options.width }}px;{% endstyle %}></div>
    Примечание. 

    Чтобы разработчику не нужно было самостоятельно подставлять эту конструкцию в созданные ранее шаблоны, можно включить поддержку обратной совместимость шаблонов. Для этого при подключении API нужно передать параметр csp с полем data_style:

    https://api-maps.yandex.ru/2.1/?lang=ru_RU&csp[data_style]=true

    В результате API автоматически будет заменять стандартную форму записи (<div style=..) на конструкцию {% style %}.

    Обратите внимание, что при использовании опции csp[data_style] могут возникнуть проблемы с производительностью. По этой причине не рекомендуется включать эту опцию.

  2. Динамически формировать стили и затем применять их к DOM-элементам средствами JavaScript. Подробнее см. пример в песочнице.