Documentation
Reference
2.1.55 (current version)
collection
interactivityModel
Interfaces

Router

The API offers a feature for building driving routes. The route between a start point and end point is calculated automatically, and an unlimited number of waypoints and throughpoints can be set on the route.

A route is built via the route function, which is passed an array of points for the route to go through, and additional route construction options, if necessary.

The route is calculated asynchronously (similar to geocoding). The result is passed to the handler function as a GeoObjectCollection collection. This object implements the IGeoObject interface, meaning it can be placed on the map.

ymaps.route(['Moscow', 'Saint Petersburg']).then(
    function (route) {
        myMap.geoObjects.add(route);
    },
    function (error) {
        alert('Error occurred: ' + error.message);
    }
);

There are three ways to set route points:

  1. An array containing a coordinate pair ([59.94, 30.31]).
  2. A string ('Saint Petersburg'). Automatically performs geocoding.
  3. Object with the type and point fields ({type: 'wayPoint', point: 'Saint Petersburg'}, {type: 'viaPoint', point: [59.94, 30.31]).

    This method allows for explicitly specifying the type of point on a route: wayPoint — waypoint, or viaPoint — throughpoint. If a string is passed in the point field, geocoding is performed automatically.

If the type of point is not specified, it is assumed to be a waypoint.

ymaps.route([
    'Yakornaya square, Kronshtadt',
    {
        type: 'viaPoint',
        point: [59.93328,30.342791]// or 'Anichkov bridge'
    },
    'Finlyandskiy train station, Saint Petersburg'// or [59.956084, 30.356849]
]).then(
    function (route) {
        myMap.geoObjects.add(route);
    },
    function (error) {
        alert("Error occurred: " + error.message);
    }
);

A route can be built either with or without consideration for traffic jams. Ignoring or calculating traffic is controlled by the avoidTrafficJams option (true/false). By default, traffic is ignored. A route that is built ignoring traffic might be different from a route between the same points that is calculated to avoid traffic jams.

ymaps.route(['Kronshtadt, Anchor Square', 'Saint Petersburg, Finlyandskiy Train Station', {avoidTrafficJams: true}]);

The created route is presented as an ordered collection of paths (router.Path) that connect the stopping points in sequential pairs. Use the getPaths method to get the route paths. For the previous example with the intermediary point “Anichkov bridge”, the code route.getPaths().getLength() returns one, since intermediary points do not affect how the route is broken into paths.

Each path is divided into segments (router.Segment), which can be obtained from the path using the getSegments method. The ends of the segments are the start and end points of paths, throughpoints, unavoidable waypoints (for example, a ferry) and points where direction may change (forks, on and off ramps, turns, U-turns, or intersections).

A segment is described by a polyline; the getCoordinates method returns the coordinates of the polyline points.

var routeLength = route.getLength(); // Route length
var firstPath = route.getPaths().get(0); // First path
var firstPathLength = firstPath.getLength(); // Length of the first path
var firtstPathTime = firstPath.getTime(); // Travel time without traffic 
var firstPathFirstSegment = firstPath.getSegments()[0];// First segment of the first path
var firstPathFirstSegmentJamsTime =  firstPathFirstSegment.getJamsTime();// Travel time accounting for traffic

For segments, data is also available for creating a route description: the direction and angle of the turn at the end of the segment, along with the name of the street it starts on.