Документация
JavaScript API 2.0
Справочник JavaScript API
2.0.46 (текущая версия)
collection
interactivityModel
theme
theme.twirl
theme.twirl.balloon
theme.twirl.geoObject
theme.twirl.geoObject.layout

Руководство по переходу на JavaScript API 2.0

Документ содержит примеры кода для выполнения основных операций с JavaScript API Яндекс.Карт первой и второй версий.

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

Версия 1.1Версия 2.0
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <!-- Загружаем API-->
        <script src="https://api-maps.yandex.ru/1.1/index.xml?key=API-ключ" type="text/javascript"></script>
        <script type="text/javascript">
            /* При успешной загрузке API выполняется 
               соответствующая функция */
            YMaps.jQuery(function () {
                …
            });
            
        </script>
    </head>
    ...
</html>

URL API: https://api-maps.yandex.ru/1.1/index.xml.

Обязательно передать API-ключ.

Загруженный API включает в себя библиотеку jQuery.

<html xmlns="http://www.w3.org/1999/xhtml">
    <head>
        <!-- Загружаем API-->
        <script src="https://api-maps.yandex.ru/2.0/?load=package.standard&mode=debug&lang=ru-RU" type="text/javascript"></script>
        <script type="text/javascript">
            /* При успешной загрузке API выполняется
               соответствующая функция */
            ymaps.ready(function () { 
                …
            });
        </script> 
    </head>
    ...
</html>

URL API: https://api-maps.yandex.ru/2.0/.

API-ключ не является обязательным.

Обязательным является параметр lang.

Доступные параметры:

  • lang - язык (обязательный параметр);
  • key - API-ключ;
  • load - пакеты, которые необходимо загрузить;
  • mode - режим работы с API. По умолчанию release (код обфусцирован, ошибки API не генерируются);
  • coordorder - порядок координат. По умолчанию принимает значение latlong (широта, долгота);
  • ns - пространство имен. По умолчанию ymaps.

API не включает в себя библиотеку jQuery и допускает пакетную загрузку (минимизация трафика).

Создание карты

Версия 1.1Версия 2.0
/* Создание экземпляра карты и его привязка 
   к контейнеру с id="YMapsID" */
var myMap = new YMaps.Map(YMaps.jQuery("#YMapsID")[0]);

// Установка для карты ее центра, типа и масштаба
myMap.setCenter(
    // Центр карты    
    new YMaps.GeoPoint(37.64, 55.76), 
    // Коэффициент масштабирования
    10, 
    // Тип карты
    YMaps.MapType.SATELLITE
)

Центр, тип и коэффициент масштабирования карты задаются после ее инициализации.

/* Создание экземпляра карты и его привязка 
   к контейнеру с id="YMapsID" */
var myMap = new ymaps.Map("YMapsID", {
        // Центр карты
        center: [55.76, 37.64],
        // Коэффициент масштабирования
        zoom: 10,
        // Тип карты
        type: "yandex#satellite"
    }
);

Центр, тип и коэффициент масштабирования карты задаются при ее инициализации.

Параметры карты

Изменение области просмотра карты

Версия 1.1Версия 2.0
myMap.setBounds(new YMaps.GeoBounds(
    /* Координаты юго-западного угла области просмотра 
       карты */
    new YMaps.GeoPoint(0, 0), 
    /* Координаты северо-восточного угла области просмотра 
       карты */
    new YMaps.GeoPoint(40, 40);
    )
)
myMap.setBounds([
    /* Координаты юго-западного угла области просмотра
       карты */
    [0, 0],
    /* Координаты северо-восточного угла области
       просмотра карты */
    [40, 40]
    ]
)

Плавное перемещение центра карты

Версия 1.1Версия 2.0
myMap.panTo(
    // Координаты нового центра карты
    new YMaps.GeoPoint(37.609,55.753), {
            /* Опции перемещения:
               разрешить уменьшать и затем увеличивать
               зум карты при перемещении между точками */   
            flying: true
        }
)
myMap.panTo(
    // Координаты нового центра карты
    [55.753, 37.609], {
        /* Опции перемещения:
           разрешить уменьшать и затем увеличивать зум
           карты при перемещении между точками 
        */
        flying: true
    }
)

Получение максимального и минимального масштабов карты

Версия 1.1Версия 2.0
/* Определение максимального значения коэффициента
   масштабирования для заданной области просмотра карты */
var maxZoom = myMap.getMaxZoom(
        new YMaps.GeoBounds(
            new YMaps.GeoPoint(0, 0), 
            new YMaps.GeoPoint(40, 40)
        )
    );

/* Определение минимального значения коэффициента
   масштабирования для заданной области просмотра карты */
var minZoom = myMap.getMinZoom(
        new YMaps.GeoBounds(
            new YMaps.GeoPoint(0, 0),
            new YMaps.GeoPoint(40, 40)
        )
    );

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

Максимальное и минимальное значения коэффициентов масштабирования определяются для заданной области просмотра карты.

/* Определение максимального и минимального 
   значений коэффициентов масштабирования
  (производится для центра карты) */
myMap.zoomRange.get(
    /* Координаты точки, в которой определяются 
       значения коэффициентов масштабирования */ 
    [55.8,37.6])
    .then(function (zoomRange, err) {
        if (!err) {
            // zoomRange[0] - минимальный масштаб
            // zoomRange[1] - максимальный масштаб
            ...
        }
    }
)

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

Максимальное и минимальное значения коэффициентов масштабирования определяются для заданной точки карты.

Поведения карты

Включение поведений карты

Версия 1.1Версия 2.0
// После создания карты включаем нужные поведения
myMap.enableRuler();
myMap.enableScrollZoom();

Включать поведения карты можно только после ее инициализации.

/* При создании карты помимо поведений "по умолчанию" 
   включаем еще дополнительные поведения (scrollZoom) */ 
var myMap = new ymaps.Map("map", {
            center: [59.93, 30.31],
            zoom: 10,
            behaviors: ["default", "scrollZoom"]
        }
    );

// Включаем поведения после создания карты
myMap.behaviors.enable("ruler");

Включать поведения карты можно как при ее создании, так и после.

Отключение поведений карты

Версия 1.1Версия 2.0
// Отключаем поведения только после создания карты
myMap.disableDragging();
myMap.disableScrollZoom();

Поведения карты отключаются после ее инициализации.

/* При инициализации карты отключаем все поведения, 
   кроме scrollZoom */
var myMap = new ymaps.Map("map", {
            center: [59.93, 30.31],
            zoom: 10,
            behaviors: ["scrollZoom"]
        }
    );

// Отключаем поведение после инициализации карты
myMap.behaviors.disable("scrollZoom");

Отключать поведения карты можно как при ее инициализации, так и после.

Добавление геообъектов на карту

Версия 1.1Версия 2.0
myMap.addOverlay(geoObject)

Все геообъекты добавляются на карту с помощью метода addOverlay().

myMap.geoObjects.add(geoObject);

Все геообъекты добавляются на карту через глобальную коллекцию map.geoObjects с помощью метода add().

Метка

Версия 1.1.Версия 2.0
// Создание метки 
var myPlacemark = new YMaps.Placemark(
        // Координаты метки
        new YMaps.GeoPoint(37.6, 55.8), {
            /* Опции метки:
               - флаг перетаскивания метки */
            draggable: true,
            /* - показывать значок метки 
               при открытии балуна */
            hideIcon: false
        }
    );

// Задание контента значка метки
myPlacemark.name = "Москва";
// Задание контента балуна
myPlacemark.description = "Столица России";

// Добавление метки на карту
myMap.addOverlay(myPlacemark); 
// Создание метки 
var myPlacemark = new ymaps.Placemark(
        // Координаты метки
        [55.8, 37.6], {
            /* Свойства метки:
               - контент значка метки */
            iconContent: "Москва",
            // - контент балуна метки
            balloonContent: "Столица России"
        }, {
            /* Опции метки:
               - флаг перетаскивания метки */
            draggable: true,
            /* - показывать значок метки 
               при открытии балуна */
            hideIconOnBalloonOpen: false
        }
    );

// Добавление метки на карту
myMap.geoObjects.add(myPlacemark);

Балун

Версия 1.1Версия 2.0
myMap.openBalloon(
    // Координаты балуна
    new YMaps.GeoPoint(37.6, 55.7),
    // Контент балуна
    "Москва", {
        /* Опции балуна:
           - балун имеет кнопку закрытия */
        hasCloseButton: true
    }
);
myMap.balloon.open(
    // Координаты балуна
    [55.76, 37.64], {
        /* Свойства балуна:
           - контент балуна */
        content: "Москва"
    }, {
        /* Опции балуна:
           - балун имеет кнопку закрытия */ 
        closeButton: true
    }
);

Всплывающая подсказка

Версия 1.1Версия 2.0
myMap.hint.show(
    // Координаты подсказки
    myMap.converter.coordinatesToLocalPixels(myMap.getCenter()), 
    // Контент подсказки
    "Москва", {
        /* Опции подсказки:
           - задержка показа хинта */
        showTimeout: 2000
    }
)

Позиция всплывающей подсказки задается локальными пиксельными координатами.

myMap.hint.show(
    // Координаты подсказки
    myMap.getCenter(), 
    // Контент подсказки
    "Москва", { 
        /* Опции подсказки:
           - задержка показа хинта */
        showTimeout: 2000
    }
)

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

Ломаная линия

Версия 1.1Версия 2.0
// Создание ломаной линии 
var myPolyline = new YMaps.Polyline(
        // Координаты линии
        [
            new YMaps.GeoPoint(37.7, 55.7),
            new YMaps.GeoPoint(37.7, 55.8),
            new YMaps.GeoPoint(37.8, 55.8),
            new YMaps.GeoPoint(37.8, 55.7),
            new YMaps.GeoPoint(37.7, 55.7)
        ], {
            /* Опции линии:
               - отключение кнопки закрытия балуна */
            hasCloseButton: false
        }
);

// Создание стиля для ломанной
var s = new YMaps.Style();
s.lineStyle = new YMaps.LineStyle();
// Цвет и прозрачность линии
s.lineStyle.strokeColor = "0000FF55";
// Ширина линии
s.lineStyle.strokeWidth = "5";

// Добавление стиля в хранилище стилей карты
YMaps.Styles.add("example#CustomLine", s);

// Задание стиля для ломаной
myLine.setStyle("example#CustomLine");

// Установка контента балуна ломаной
myPolyline.setBalloonContent("Ломаная линия");

// Добавление линии на карту
myMap.addOverlay(myPolyline);
// Создание ломаной линии
var myPolyline  = new ymaps.Polyline([
        // Координаты вершин ломаной
            [55.80, 37.30],
            [55.80, 37.40],
            [55.70, 37.30],
            [55.70, 37.40]
        ], {
            /* Свойства линии:
               - балун ломаной */
            balloonContent: "Ломаная линия"
        }, {
            /* Опции линии: 
               - отключение кнопки закрытия балуна */
            balloonCloseButton: false,
            // - цвет  и прозрачность линии
            strokeColor: "0000FF55",
            // - ширина линии
            strokeWidth: 5
         }
    );

// Добавление линии на карту
myMap.geoObjects.add(myPolyline);

Многоугольник

Версия 1.1Версия 2.0
// Создание многоугольника
var myPolygon = new YMaps.Polygon([
            // Координаты многоугольника 
            new YMaps.GeoPoint(37.7, 55.7),
            new YMaps.GeoPoint(37.7, 55.8),
            new YMaps.GeoPoint(37.8, 55.8),
            new YMaps.GeoPoint(37.8, 55.7)
        ]
),
  
    // Создание стиля многоугольника
    style = new YMaps.Style();
style.polygonStyle = new YMaps.PolygonStyle();
// Флаг использования заливки
style.polygonStyle.fill = true;
// Флаг отрисовки контурной линии
style.polygonStyle.outline = true;
// Ширина линии
style.polygonStyle.strokeWidth = 10;
// Цвет и прозрачность линии
style.polygonStyle.strokeColor = "ffff0088";
// Цвет и прозрачность заливки
style.polygonStyle.fillColor = "ff000055";

// Задание стиля для многоугольника
myPolygon.setStyle(style);

// Задание контента всплывающей подсказки многоугольника
myPolygon.setHintContent = ("Многоугольник");

// Добавление многоугольника на карту
myMap.addOverlay(myPolygon);

Если координаты первой и последней вершин многоугольника не совпадают, то при его отрисовке эти вершины будут автоматически соединены.

// Создание многоугольника
var myPolygon = new ymaps.Polygon([
            // Координаты многоугольника 
            [
               [55.75, 37.50],
               [55.76, 37.60],
               [55.80, 37.70],
               [55.69, 37.72]
            ]
        ], {
            /* Свойства многоугольника:
               - контент хинта */
            hintContent: "Многоугольник"            
        }, {
            /* Опции многоугольника:
               - флаг использования заливки */ 
            fill: true,
            // - флаг отрисовки контурной линии
            stroke: true,
            // - ширина линии
            strokeWidth: 5,             
            // - цвет и прозрачность линии
            strokeColor: "ffff0088",
            // - цвет и прозрачность заливки
            fillColor: "ff000055"
         }
    );
 
// Добавление многоугольника на карту 
myMap.geoObjects.add(myPolygon);

Если у многоугольника координаты первой и последней вершин не совпадают, то при создании этого многоугольника добавится еще одна вершина, совпадающая с первой.

Коллекции

Создание коллекции

Версия 1.1Версия 2.0
var myCollection = new YMaps.GeoObjectCollection();
var myCollection = new ymaps.GeoObjectCollection();

Отображение элементов коллекции на карте

Версия 1.1Версия 2.0
// Создание метки
var myPlacemark = new YMaps.Placemark(new YMaps.GeoPoint(37.64, 55.76));

// Добавление объекта (метки) в коллекцию
myCollection.add(myPlacemark);

// Добавление коллекции на карту
myMap.addOverlay(myCollection);
// Создание метки 
var myPlacemark = new ymaps.Placemark([55.8,37.6]);

// Добавление объекта (метки) в коллекцию
myCollection.add(myPlacemark);

// Добавление коллекции на карту
myMap.geoObjects.add(myCollection);

Удаление элементов из коллекции

Версия 1.1Версия 2.0
// Удаление одного элемента из коллекции
myCollection.remove(myPlacemark);

// Удаление всех элементов из коллекции
myCollection.removeAll();
// Удаление одного элемента из коллекции
myCollection.remove(myPlacemark);

// Удаление всех элементов из коллекции
myCollection.removeAll();

Задание стиля для элементов коллекции

Версия 1.1Версия 2.0
// Задание стиля для коллекции при ее создании
var myCollection = new YMaps.GeoObjectCollection("default#greenPoint"); 

// Задание стиля коллекции после ее создания
myCollecton.setStyle("default#redPoint")
// Задание стиля для коллекции при ее создании
var myCollection = new ymaps.GeoObjectCollection({}, {
            preset: "twirl#greenIcon" 
        }
    );

// Задание стиля коллекции после ее создания
myCollection.options.set("preset", "twirl#redIcon");

Элементы управления картой

Добавление элементов управления на карту

Версия 1.1Версия 2.0
// Добавление стандартного набора кнопок
myMap.addControl(new YMaps.ToolBar());
// Добавление кнопки изменения масштаба
myMap.addControl(new YMaps.Zoom());
// Добавление списка типов карты
myMap.addControl(new YMaps.TypeControl());
// Добавление стандартного набора кнопок
myMap.controls.add("mapTools")
    // Добавление кнопки изменения масштаба 
    .add("zoomControl")
    // Добавление списка типов карты
    .add("typeSelector");

Удаление элементов управления с карты

Версия 1.1Версия 2.0
// Удаление стандартного набора кнопок
myMap.removeControl(new YMaps.ToolBar());
// Удаление кнопки изменения масштаба
myMap.removeControl(new YMaps.Zoom());
// Удаление списка типов карты
myMap.removeControl(new YMaps.TypeControl());
// Удаление стандартного набора кнопок
myMap.controls.remove("mapTools")
    // Удаление кнопки изменения масштаба
    .remove("zoomControl")
    // Удаление списка типов карты
    .remove("typeSelector");

События

Добавление обработчика события карты

Версия 1.1Версия 2.0
/* При щелчке на карте показывается балун со 
   значениями координат в месте клика */
YMaps.Events.observe(myMap, myMap.Events.Click, 
    function (myMap, mEvent) {
        myMap.openBalloon(
            // Позиция балуна
            mEvent.getGeoPoint(),
            // Контент балуна
            "Значение: " + mEvent.getGeoPoint()
       );
    }
);
/* При щелчке на карте показывается балун со
   значениями координат в месте клика */
myMap.events.add("click",
    function(e) {
        myMap.balloon.open(
            // Позиция балуна
            e.get("coordPosition"), {
                // Свойства балуна:
                // контент балуна
                contentBody: "Значение: " +
                e.get("coordPosition")
            }   
        )
    }
);

Удаление обработчика события

Версия 1.1Версия 2.0
// Удаление обработчика события после того, как событие произошло
var myEventListener = YMaps.Events.observe(map, map.Events.Click, 
        function (map, mEvent) {
            alert("Щелк!");
            myEventListener.cleanup();
        }
    );
// Удаление обработчика события после того, как событие произошло
var onClick = function() {
        alert("Щелк!");
        myMap.events.remove("click", onClick);
    };

myMap.events.add("click", onClick);

Геопоиск

Прямое геокодирование

Версия 1.1Версия 2.0
var geocoder = new YMaps.Geocoder(
        // Строка с адресом, который нужно геокодировать
        "Москва", {
            /* Опции поиска:
               - область поиска */
            boundedBy: myMap.getBounds(),
            // - искать только в этой области
            strictBounds: true,
            // - требуемое количество результатов
            results: 1
        }
    );

/* Размещение полученной коллекции
   геообъектов на карте */
myMap.addOverlay(geocoder);
var myGeocoder = ymaps.geocode(
        // Строка с адресом, который нужно геокодировать
        "Москва", {
            /* Опции поиска:
               - область поиска */
            boundedBy: myMap.getBounds(),
            // - искать только в этой области
            strictBounds: true,
            // - требуемое количество результатов
            results: 1
        }
    );

/* После того, как поиск вернул результат, вызывается
   callback-функция */
myGeocoder.then(
    function (res) {
        /* Размещение полученной коллекции 
           геообъектов на карте */
        myMap.geoObjects.add(res.geoObjects);
    }
);

Обработка событий геокодера

Версия 1.1Версия 2.0
/* Добавление обработчика события "Load" (геокодирование
   успешно закончено) */
YMaps.Events.observe(geocoder, geocoder.Events.Load,
    function () {
        if (this.length()) {
            // Добавление первого полученного объекта на карту
                        myMap.addOverlay(this.get(0));
            // Центрирование карты на добавленном объекте
            myMap.panTo(this.get(0).getGeoPoint())
        } else {
            alert("Ничего не найдено");
        }
    }
)

/* Добавление обработчика события "Fault" (при
   выполнении геокодирования произошла ошибка) */
YMaps.Events.observe(geocoder, geocoder.Events.Fault, 
    function (error) {
        alert("Произошла ошибка: " + error.message)
    }
)
// Результат поиска передается в callback-функцию
myGeocoder.then(
    function (res) {
        if (res.geoObjects.getLength()) {
            // point - первый элемент коллекции найденных объектов
            var point = res.geoObjects.get(0);
            // Добавление полученного элемента на карту
            myMap.geoObjects.add(point);
            // Центрирование карты на добавленном объекте
            myMap.panTo(point.geometry.getCoordinates());
        }
    },
    // Обработка ошибки
    function (error) {
        alert("Возникла ошибка: " + error.message);
    }
)

Маршрутизатор

Создание маршрута

Версия 1.1Версия 2.0
var router = new YMaps.Router([
        // Список точек, которые необходимо посетить
        'Арбатская',
        'Кропоткинская',
        // Метро 'Третьяковская'
        new YMaps.GeoPoint(37.62561,55.74062)
    ],
        // Кропоткинская — транзитная точка
    [1], {
        /* Опции маршрутизатора: 
           - автоматически позиционировать карту */
        viewAutoApply: true 
    });

Точки маршрута можно задавать, указав либо их координаты (объект класса YMaps.GeoPoint), либо адрес.

var myRouter = ymaps.route([
        // Список точек, которые необходимо посетить
        'Москва, метро Арбатская', {
            // Кропоткинская — транзитная точка
            type: "viaPoint",                   point: "Москва, метро Кропоткинская"
        },
        [55.74062, 37.62561] // метро "Третьяковская"
    ], {
        /* Опции маршрутизатора:
           - автоматически позиционировать карту */
        mapStateAutoApply: true 
    });

Точки маршрута могут быть заданы в одном из следующих форматов:

  • адрес точки;
  • объект с полями type (тип точки) и point (адрес точки);
  • массив координат точки.

Добавление маршрута на карту

Версия 1.1Версия 2.0
// Добавление маршрута на карту
myMap.addOverlay(router);
/* После того, как маршрут был построен, вызывается
   callback-функция */ 
myRouter.then(function(route) {
    // Добавление маршрута на карту
    myMap.geoObjects.add(route);
    }
);

Обработка событий маршрутизатора

Версия 1.1Версия 2.0
/* Добавление обработчика события "Success" (успешное 
   построение маршрута) */
YMaps.Events.observe(router, router.Events.Success, function() {
        // Задание текста для меток
        router.getWayPoint(0).setIconContent("А");
        router.getWayPoint(1).setIconContent("Б");
       // Добавление маршрута на карту
       myMap.addOverlay(router);
});

/* Добавление обработчика события "Error" (неудачное
   построение маршрута) */
YMaps.Events.observe(router, router.Events.RouteError, 
    function (link, num) {
        alert("Не удается проложить маршрут до точки " + num);
    }
)
/* В случае успешного построение маршрута вызывается
   callback-функция */
myRouter.then(function(route) {
        /* Задание контента меток в начальной и 
           конечной точках */
        var points = route.getWayPoints();         points.get(0).properties.set("iconContent", "А");
        points.get(1).properties.set("iconContent", "Б");
        // Добавление маршрута на карту
        myMap.geoObjects.add(route);
    },
    // Обработка ошибки
    function (error) {
        alert("Возникла ошибка: " + error.message);
    }
)