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

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

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
       <script src="https://api-maps.yandex.ru/2.0-stable/?apikey=ваш API-ключ&?apikey=ваш API-ключ&load=package.standard&lang=ru-RU" type="text/javascript"> </script>
    </head>
</html>

Примечание

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

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

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

URL для загрузки имеет вид

(http|https)://api-maps.yandex.ru/`<`номер версии`>`/?apikey=ваш API-ключ&lang=`<`идентификатор языка`>``&load=<загружаемые пакеты>`&`<`дополнительные параметры`>`

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

(http|https)://enterprise.api-maps.yandex.ru/<номер версии>/?apikey=ваш API-ключ&lang=`<`идентификатор языка`>`&load=<загружаемые пакеты>&apikey=<API ключ>&<дополнительные параметры>

Нумерация версий описана в разделе Версии API.

Компоненты API могут быть загружены как по протоколу HTTP, так и по HTTPS. Если сайт поддерживает работу по обоим протоколам, можно опустить явное указание схемы в атрибуте src элемента script.

<script src="//api-maps.yandex.ru/2.0/?apikey=ваш API-ключ&load=package.standard&lang=ru-RU" type="text/javascript">
</script>

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

Параметр	Обязательный параметр	Описание
lang		Идентификатор языка - локаль. Задается в виде - в соответствии с RFC-3066. В настоящий момент поддерживаются следующие локали: ru-RU — русский язык; en-US — английский язык; tr-TR — турецкий язык; uk-UA — украинский язык. Задание локали определяет язык, на котором отображаются надписи на карте и элементах управления, предпочтительный язык, на котором возвращаются результаты поиска по карте и используемые по умолчанию единицы измерения.
load		Список загружаемых пакетов. Имена пакетов перечисляются через запятую. Например, `load=package.standard,package.geoObjects`. Могут быть загружены как все компоненты API (`load=package.full`) так и отдельные пакеты. Это позволяет минимизировать объем трафика, передаваемого клиентскому приложению. Примечание Рекомендуется загружать пакет package.standard, содержащий стандартный набор компонентов для работы с API. Компоненты также можно загружать «по требованию», используя функцию load.
apikey*		API-ключ. Используется только в платных версиях API. Получить ключ можно в кабинете разработчика. Примечание Ключ будет активирован только после заключения лицензионного договора с Яндексом.
coordorder		Порядок задания географических координат в функциях API, принимающих на вход пары долгота-широта (например, Placemark). Возможные значения: `latlong`— [широта, долгота] — используется по умолчанию; `longlat`— [долгота, широта]. Значение по умолчанию: `latlong`.
mode		Режим загрузки API. Код API может быть загружен в упакованном виде для минимизации трафика и скорости исполнения в браузере (`mode=release`), а также в виде исходного кода (`mode=debug`). Загрузка в виде исходного кода удобна для отладки JavaScript-компонентов — код всех загруженных компонентов доступен для просмотра. Кроме того, в этом режиме в консоль выводятся сообщения об ошибках и исключениях. При загрузке в упакованном виде эти сообщения не выводятся. Значение по умолчанию: `release`.
ns		Пространство имен, в котором локализованы программные компоненты API. По умолчанию все объекты принадлежат пространству имен `ymaps` (например, ymaps.load, ymaps.Map). Если при загрузке API указать `ns=myNameSpace`, то объекты будут доступны уже как `myNameSpace`.load, `myNameSpace`.Map. Использование пространства имен позволяет избежать пересечения названий функций и прочих программных компонентов, используемых в API и пользовательском/стороннем коде. Значение по умолчанию: `ymaps`.
onload		Имя функции, которую необходимо вызвать после того, как компоненты API будут загружены и готовы к использованию (callback). Допускается использование вложенных пространств имён: `onload=myfunction` `onload=myapp.dosmth` Пример использования приведен в таблице ниже.

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

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

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

<script src="https://api-maps.yandex.ru/2.0-stable/?apikey=ваш API-ключ&load=package.map&lang=ru-RU"type="text/javascript"></script>
<script type="text/javascript">
    if (window.location.pathname == '/traffic-page') {
        // На этой странице нужно показать пробки и инструмент поиска по карте
        ymaps.load(['package.traffic', 'package.search'], addControls);
    }
    function addControls(map) {
        map.controls.add('trafficControl').add('searchControl');
    }
</script>

Готовность API

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

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

Использование функции ready()

Использование параметра загрузки onload

<script src="http://...?load=package.standard&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() {
        myMap = new ymaps.Map("YMapsID", {
            center: [55.87, 37.66],
            zoom: 10
        });
        ...
    }
</script>

// Сразу после загрузки API будет вызвана функция init. На момент ее исполнения div-контейнер карты уже будет готов.
<script src="http://...?load=package.standard&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

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

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

Готовность API

Была ли статья полезна?