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

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

<head>
  <!-- Обратите внимание, в ссылке подключения необходимо указывать
  протокол HTTPS. -->
  <script src="https://api-maps.yandex.ru/2.1/?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/<номер версии>/?lang=<идентификатор языка>&<дополнительные параметры>
Для коммерческих версий API ссылка для загрузки имеет вид:
https://enterprise.api-maps.yandex.ru/<номер версии>/?lang=<идентификатор языка>&apikey=<API-ключ>&<дополнительные параметры>

В таблице ниже описаны параметры, которые можно указать при загрузке 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.
Примечание. В ранних версиях API локаль указывалась через дефис. Например, ru-RU. Данное обозначение поддерживается в целях сохранения обратной совместимости, но не рекомендуется к использованию.

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. В эту функцию в качестве аргумента будет передан объект, содержащий информацию об ошибке.

apikey * (только для платной версии API)

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

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

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

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

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

<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()
<script src="https://api-maps.yandex.ru/2.1/?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://...?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/?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/?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. Подробнее см. пример в песочнице.