Документация
Справочник JavaScript API
2.1.60 (текущая версия)
collection
interactivityModel
Interfaces

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

API предоставляет возможность прокладывания автомобильных маршрутов. Маршрут между начальным и конечным пунктом вычисляется автоматически, при этом можно задать произвольное количество точек остановки и транзитных точек маршрута.

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

Вычисление маршрута производится асинхронно (аналогично геокодированию). Результат передается в функцию-обработчик в виде коллекции GeoObjectCollection. Этот объект реализует интерфейс IGeoObject, то есть может быть размещен на карте.

ymaps.route(['Москва', 'Санкт-Петербург']).then(
    function (route) {
        myMap.geoObjects.add(route);
    },
    function (error) {
        alert('Возникла ошибка: ' + error.message);
    }
);

Существует три способа задания точки маршрута:

  1. Пара координат в виде массива ([59.94, 30.31]).
  2. Строка ('Санкт-Петербург'). Производится автоматическое геокодирование.
  3. Объект с полями type и point ({type: 'wayPoint', point: 'Санкт-Петербург'}, {type: 'viaPoint', point: [59.94, 30.31]).

    Этот способ позволяет в явном виде указать тип точки маршрута: wayPoint — точка остановки, viaPoint — транзитная точка. Если в поле point передана строка, производится автоматическое геокодирование.

Если тип точки не указан, она считается точкой остановки.

ymaps.route([
    'Кронштадт, Якорная площадь',
    {
        type: 'viaPoint',
        point: [59.93328,30.342791]// или 'Аничков мост'
    },
    'Санкт-Петербург, Финляндский вокзал'// или [59.956084, 30.356849]
]).then(
    function (route) {
        myMap.geoObjects.add(route);
    },
    function (error) {
        alert("Возникла ошибка: " + error.message);
    }
);

Прокладывать маршрут можно как с учетом так и без учета пробок. Игнорирование или учет пробок регулируется опцией avoidTrafficJams (true/false). По умолчанию пробки не учитываются. Маршрут, проложенный без учета пробок, может отличаться от маршрута, проложенного между теми же точками, но с учетом пробок.

ymaps.route(['Кронштадт, Якорная площадь', 'Санкт-Петербург, Финляндский вокзал'], {avoidTrafficJams: true});

Построенный маршрут представляется в виде упорядоченной коллекции путей (router.Path), попарно последовательно соединяющих точки остановки. Получить пути маршрута можно с помощью метода getPaths. Для предыдущего примера с промежуточной точкой «Аничков мост» код route.getPaths().getLength() возвратит единицу, так как промежуточные точки не влияют на разбиение маршрута на пути.

Каждый путь разбивается на сегменты (router.Segment), получить которые из пути можно с помощью метода getSegments. Концами сегментов являются начальные и конечные точки путей, транзитные точки, точки вынужденной остановки (например, паром) и точки возможного изменения направления движения (развилка, въезд, съезд, поворот, разворот, перекресток).

Сегмент описывается ломаной, координаты точек ломаной возвращаются методом getCoordinates.

var routeLength = route.getLength(); // Длина маршрута
var firstPath = route.getPaths().get(0); // Первый путь
var firstPathLength = firstPath.getLength(); // Длина первого пути
var firtstPathTime = firstPath.getTime(); // Время без учета пробок
var firstPathFirstSegment = firstPath.getSegments()[0];// Первый сегмент первого пути
var firstPathFirstSegmentJamsTime =  firstPathFirstSegment.getJamsTime();// Время с пробками

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