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

Внимание. Маршрутизация доступна только в актуальных версиях API.

Как перейти на API 2.1

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

Точки маршрута

Для прокладывания маршрута используется класс YMaps.Router, которому необходимо передать точки остановки и транзитные точки маршрута.

(YMaps.WayPoint) — точка, в которой предполагается или возможна остановка. Начальная и конечная точки маршрута всегда являются точками остановки.

(YMaps.ViaPoint) — точка, в которой остановка не предполагается, но через которую нужно проложить маршрут. Массив индексов транзитных точек передается вторым параметром конструктора YMaps.Router. Нумерация индексов начинается с нуля (см. пример ниже).

var router = new YMaps.Router(['Арбатская', 'Кропоткинская','Третьяковская'],
                               [1]);// Кропоткинская — транзитная точка.

Открыть пример в новом окне

Точки маршрута можно задать, указав либо их координаты, либо адрес. Во втором случае координаты будут вычислены автоматически с помощью геокодера (см. пример ниже):

var router = new YMaps.Router([new YMaps.GeoPoint(37.658509,55.758331),
                               new YMaps.GeoPoint(37.594306,55.735429)]);

или

var router = new YMaps.Router(['Москва, Курская', 'Москва, Парк культуры']);

Если через какую-то точку невозможно проложить маршрут (например, точка находится вне трассы), маршрутизатор попытается проложить маршрут максимально близко к ней.

События построения маршрута

Во время построения маршрута объекты класса YMaps.Router генерируют события, которые могут быть обработаны стандартными средствами JavaScript API. Построение маршрута — асинхронная операция, поэтому оперировать объектами класса YMaps.Router можно только после того, как было сгенерировано событие Success (см. пример ниже).

var router = new YMaps.Router(['Москва, Арбатская',
                               'Москва, метро Китай-Город',
                               'Москва, метро Третьяковская']);
YMaps.Events.observe(router, router.Events.Success, function() {
router.getWayPoint(0).setIconContent('Точка отправления');
router.getWayPoint(1).setIconContent('Точка прибытия');
      map.addOverlay(router);
});

Открыть пример в новом окне

События генерируются следующим образом. Вначале отправляется запрос серверу. Если ответ получен, генерируется событие Load, в противном случае — событие Fault. Эти два события показывают, может ли быть установлено соединение с сервером.

Если соединение с сервером установлено, производится попытка построения маршрута. Если маршрут проложен, генерируется событие Success. В противном случае генерируется одно из событий GeocodeError или RouteError, отражающих причины, по которым не удалось вычислить маршрут. При этом в обработчик события будет передан индекс точки, которую не удалось геокодировать или до которой невозможно проложить маршрут.

Пример: неудачное геокодирование
var router = new YMaps.Router(['Москва', 'Атлантида']);
map.addOverlay(router);

YMaps.Events.observe(router, router.Events.GeocodeError, function (link, number) {
   alert('Ошибка при геокодировании точки № ' + number);
})
Пример: недоступность точки
var router = new YMaps.Router(['Москва, Курская', 'Сидней']);
map.addOverlay(router);

YMaps.Events.observe(router, router.Events.RouteError, function (link, number) {
   alert('Не удается проложить маршрут до точки № ' + number);
}); 

Отрезки маршрута

YMaps.Router задает отрезок между двумя соседними точками остановки. Таким образом, если в конструктор маршрутизатора передано 3 точки остановки, то будет доступно два отрезка маршрута.

Проложенный с помощью YMaps.Router маршрут представляется в виде списка объектов YMaps.Route. Для определения количества объектов YMaps.Route используется метод getNumRoutes(). Для доступа к конкретному объекту YMaps.Route по его индексу используется метод getRoute().

var router = new YMaps.Router(['Арбатская', 'Кропоткинская','Третьяковская']);
var route = [];
for (var i=0; i<router.getNumRoutes(); i++) {
   route[i] = route.getRoute(i);
}

Объекты класса YMaps.Route описывают траекторию перемещения с помощью ломаной линии (YMaps.Polyline), которая разбивается на отрезки (YMaps.RouteSegment). Класс YMaps.RouteSegment описывает логически выделенный отрезок маршрута. Достижение конца отрезка, при движении по маршруту, может указывать, например, на то, что производится выезд на другую улицу или на то, что в данном месте возможен поворот.

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

var router = new YMaps.Router(['Арбатская', 'Кропоткинская','Третьяковская']);
var route1 = route.getRoute(0);
var fullDistance = router.getDistance();
var firstDistance = route1.getDistance();
var firstTime = route1.getDuration();
Для определения количества отрезков в маршруте используется метод getNumRouteSegments(). Для доступа к конкретному отрезку по его индексу используется метод getRouteSegment(). Нумерация индексов начинается с нуля.
Примечание. По умолчанию отрезки маршрута не обрабатывают действия пользователя и не генерируют событий, т. к. для них режим интерактивности установлен в значение YMaps.Interactivity.NONE. Для обработки событий необходимо поменять значение интерактивности у отрезков маршрута.

Отображение маршрута на карте

Класс YMaps.Router реализует интерфейс YMaps.IOverlay, т.е. проложенный маршрут может быть сразу помещен на карту. Использование опции viewAutoApply позволяет автоматически подбирать центр и масштаб карты таким образом, чтобы маршрут был виден на карте целиком и при этом уровень масштабирования карты был максимален.

Пример

Пример добавляет на карту схему проезда ст.м. Арбатская - Кропоткинская - Третьяковская. Полный маршрут делится на два: Арбатская - Кропоткинская и Кропоткинская - Третьяковская. Пример создает простейший маршрутный лист, позволяющий проехать по второму маршруту

var router = new YMaps.Router(
       // Список точек, которые необходимо посетить
       ['Арбатская','Кропоткинская','Третьяковская'],[],
       { viewAutoApply: true }
   );
map.addOverlay(router); // Добавляет на карту полный маршрут

YMaps.Events.observe(router, router.Events.Success, function () {
   var route = router.getRoute(1);
   var itineraryList = ['Трогаемся.'];
   var action = [];
   action['back'] = 'назад';
   action['left'] = 'налево';
   action['right'] = 'направо';
   action['none'] = 'прямо';
   
   for (var i=0; i < route.getNumRouteSegments(); i++) {
      var segment = route.getRouteSegment(i);
      itineraryList.push('Едем ' + action[segment.getAction()] + " на " + segment.getStreet() + ', проезжаем ' + segment.getDistance() + ' м.');
   }
   
   itineraryList.push('Останавливаемся.');
   alert(itineraryList.join('\n'));
});

Открыть пример в новом окне