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

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

<head>
  <script src="https://api-maps.yandex.ru/2.1/?apikey=<ваш API-ключ>&lang=ru_RU"
  type="text/javascript">
  </script>
</head>
Внимание.

Для пользователей, которые работают в браузерах IE8, IE9 и IE10, будет подключаться версия 2.1.oldie.1 (даже если в ссылке подключения указана другая версия API). Версия 2.1.oldie.1 функционально соответствует версии 2.1.59 и не содержит более поздних обновлений.

Если необходимо поддерживать браузеры IE8, IE9 и IE10, при написании кода ориентируйтесь на справочник версии 2.1.59 (скачать справочник). Использование функциональности более поздних версий может привести к некорректной работе API в IE8, IE9 и IE10.

Подробнее о версионировании 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

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

В таблице ниже описаны параметры, которые можно указать при загрузке API.

Параметр Описание
apikey *

Обязательный параметр.

API-ключ. Получить ключ можно в Кабинете разработчика.

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.

coordorder

Порядок задания географических координат при работе API.

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

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

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 (то есть последнюю стабильную версию):

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

    https://api-maps.yandex.ru/2.1-dev?apikey=<ваш API-ключ>&lang=ru_RU

    Релиз-кандидат — это новая версия API, которая доступна для открытого использования, но находится на стадии утверждения. Используя релиз-кандидат в своих проектах, вы поможете нам своевременно выявить возможные ошибки. Кроме того, вы сможете заранее протестировать работу приложения с новой версией API.

  • Подключить фиксированную версию API:

    https://api-maps.yandex.ru/2.1.68?apikey=<ваш API-ключ>&lang=ru_RU
    Примечание. Если вы используете фиксированную версию, старайтесь регулярно переключать ее на более свежую версию (например, раз в несколько месяцев). Дело в том, что со временем мы можем отключить минорную версию, которую вы используете в своем проекте, и тогда у вас автоматически подключится текущая версия API. Но может оказаться, что при смене версий ваше приложение стало работать некорректно. Поэтому мы рекомендуем следить за обновлениями API и своевременно переключаться на более свежие версии.

Подробнее про версионирование в API см. в разделе Версии JavaScript API.

Загрузка API по требованию

С помощью функции modules.require можно загружать отдельные компоненты API. Это бывает полезно, когда нужно загрузить какие-нибудь компоненты API по требованию. Кроме того, это позволяет минимизировать объем трафика.

<script src="https://api-maps.yandex.ru/2.1/?apikey=<ваш API-ключ>&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()
<script src="https://api-maps.yandex.ru/2.1?apikey=<ваш API-ключ>&load=package.full&lang=ru_RU">
</script>
<script type="text/javascript">
  ymaps.ready(function () {
    var myMap = new ymaps.Map("YMapsID", {
      center: [55.76, 37.64],
      zoom: 10
    });
  });
</script>

// Формирование div-контейнер карты.
<div id="YMapsID" style="width: 450px; height: 350px;"></div>
Использование параметра загрузки onload
<script src="https://https://api-maps.yandex.ru?apikey=<ваш API-ключ>&load=package.full&lang=ru_RU&onload=init">
</script>
<script type="text/javascript">
    // Сразу после загрузки API будет 
    // вызвана функция init.
    // На момент ее исполнения div-контейнер 
    // карты уже будет готов.
    function init (ymaps) {
        var myMap = new ymaps.Map("YMapsID", {
            center: [55.87, 37.66],
            zoom: 10
        });
    }
</script>

// Формирование div-контейнер карты.
<div id="YMapsID" style="width: 450px; height: 350px;"></div>  

Возникновение событий загрузки 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/?apikey=<API-ключ>&lang=ru_RU&csp=true

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

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

img-src

Для директивы img-src в список разрешенных источников необходимо добавить домены:
  • https://*.maps.yandex.net (для загрузки тайлов);
  • api-maps.yandex.ru (для загрузки курсоров и т. п.);
  • https://yandex.ru.

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

img-src data: https://*.maps.yandex.net api-maps.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 ...;
connect-src
Для директивы connect-src следует разрешить домены:
  • https://api-maps.yandex.ru
  • https://suggest-maps.yandex.ru
  • https://*.maps.yandex.net
  • https://yandex.ru
connect-src 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/?apikey=<API-ключ>&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&apikey=<API-ключ>

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

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

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