Routing panel

Overview

The routing panel is an interface control for users to set routes on the map. The panel can be used to enter the start and ending points of the route, choose the type of route, or remove the route from the map.

If the start and ending points are moved, the route is reset automatically.

Several optimal routes are built for the specified points. The fastest route is selected as the active route and shown in purple. Alternative routes are gray. All routes account for traffic.

The routing panel doesn't support intermediary points — routes can only have two points. If you need to build a route with three or more points, use the multiRouter.MultiRoute class.
Attention. Routing requests are fee-based.

Adding the panel to a map

The routing panel is implemented by the control.RoutePanel class and accessible via the 'routePanelControl' key. You can add the panel to a map by using the controls field when creating a map:

var myMap = new ymaps.Map('map', {
    center: [55.75, 37.57],
    zoom: 9,
    controls: ['routePanelControl']
});
  
/*
// The second way to add the panel to a map.
// Note: don't forget to delete 'routePanelControl'
// from the map's controls option.
var routePanelControl = new ymaps.control.RoutePanel();
myMap.controls.add(routePanelControl); 
*/
Copied to clipboard
View the complete example code
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
    var myMap = new ymaps.Map('map', {
        center: [55.75, 37.57],
        zoom: 9,
        controls: ['routePanelControl']
    });
  
    /*
    // The second way to add the panel to a map.
    // Note: don't forget to delete 'routePanelControl'
    // from the map's controls option.
    var routePanelControl = new ymaps.control.RoutePanel();
    myMap.controls.add(routePanelControl); 
    */  
});
</script>  
Copied to clipboard

You can use the API to collapse the panel on the map. To do this, use the control.RouteButton control that is accessible via the 'routeButtonControl' key:

var myMap = new ymaps.Map('map', {
    center: [55.75, 37.57],
    zoom: 9,
    controls: ['routeButtonControl']
});
  
/*
// The second way to add a routing button to a map.
// Note: don't forget to delete 'routeButtonControl'
// from the map's controls option.
var routeButtonControl = new ymaps.control.RouteButton();
myMap.controls.add(routeButtonControl); 
*/
Copied to clipboard
View the complete example code
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
   var myMap = new ymaps.Map('map', {
       center: [55.75, 37.57],
       zoom: 9,
       controls: ['routeButtonControl']
   });
  
    /*
    // The second way to add the panel to a map.
    // Note: don't forget to delete 'routeButtonControl'
    // from the map's controls option.
    var routeButtonControl = new ymaps.control.RouteButton();
    myMap.controls.add(routeButtonControl); 
    */
});
</script>  
Copied to clipboard

Configuring the routing panel

You can configure various settings for the routing panel. For example, you can set route points, select a routing type, or set the size of the panel on the map. Specific examples below show how to configure panel settings:

For ways to accomplish other common tasks, see the section Solving typical tasks.

Setting route points

Use the fromand to fields to set route points:

var myMap = new ymaps.Map('map', {
    center: [55.753994, 37.622093],
    zoom: 9,
    controls: ['routePanelControl']
});

// Get a reference to the routing panel.
var control = myMap.controls.get('routePanelControl');

// Set states for the routing panel.
control.routePanel.state.set({
    // Address of the starting point.
    from: '16 Lva Tolstogo, Moscow',
    // Address of the ending point.
    to: 'Cheryomushki metro station, Moscow'
});
Copied to clipboard
View the complete example code
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
    var myMap = new ymaps.Map('map', {
        center: [55.753994, 37.622093],
        zoom: 9,
        controls: ['routePanelControl']
    });

    // Get a reference to the routing panel.
    var control = myMap.controls.get('routePanelControl');

    // Set states for the routing panel.
    control.routePanel.state.set({
        // Address of the starting point.
        from: '16 Lva Tolstogo, Moscow',
        // Address of the ending point.
        to: 'Cheryomushki metro station'
    });
});
</script>
Copied to clipboard
Attention. For points that are set as a string, requests will be sent to the Geocoder. Each point is counted as a separate request. In addition, enabling the reverseGeocoding option will also create extra requests to the Geocoder. Remember that geocoding requests are fee-based.

Open the interactive example in the sandbox: Route from a point on the map.

Selecting the routing type

The routing type is set in the type field:

// Get a reference to the panel.
var control = myMap.controls.get('routePanelControl');
    
control.routePanel.state.set({
    // For a list of all settings, see the reference guide.
    // The default routing type
    type: "pedestrian", // walking
});

control.routePanel.options.set({
    // Routing types that will be available
    // for users to select.
    // In the example, you can build a driving
    // route for ordering a taxi and a walking route.
    types: {
        "pedestrian": true,
        "taxi": true
    }
}); 
Copied to clipboard
View the complete example code
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
    var myMap = new ymaps.Map('map', {
        center: [55.753994, 37.622093],
        zoom: 9,
        controls: ['routePanelControl']
    });

    // Get a reference to the panel.
    var control = myMap.controls.get('routePanelControl');
    
    // Routing data is set in the 'state' field.
    control.routePanel.state.set({
        // For a list of all settings, see the reference guide.
        // The default routing type.
        type: "pedestrian",
    });
    
    control.routePanel.options.set({
        // Routing types that will be available
        // for users to select.
        // In the example, users can only build
        // a taxi route and a walking route.
        types: {
            "pedestrian": true,
            "taxi": true
        }
    });
});
</script>
Copied to clipboard

Building a route that can be used to order a taxi

The routing panel allows building routes for ordering a taxi. The map shows the driving directions and information about the trip using data from “Yandex.Taxi” (duration and approximate cost). When the user clicks the Order taxi button, a Yandex.Taxi page opens with the specified route.

To set a route with a taxi button, specify the “taxi” routing type:

// Get a reference to the panel.
var control = myMap.controls.get('routePanelControl');

control.routePanel.options.set({
    // Routing types to show on the panel.
    // Users can switch between these types.
    types: {
       auto: true,
       pedestrian: true,
       // Add the “taxi” icon
       // to the panel.
       taxi: true
    }
});

control.routePanel.state.set({
    // Use the route with the taxi button
    // by default.
    type: "taxi",
    from: '16 Lva Tolstogo, Moscow',
    to: 'Cheryomushki metro station'
});
Copied to clipboard
View the complete example code
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
    var myMap = new ymaps.Map('map', {
        center: [55.75, 37.57],
        zoom: 9,
        controls: ['routePanelControl']
    });

    // Get a reference to the panel.
    var control = myMap.controls.get('routePanelControl');

    control.routePanel.options.set({
        // Routing types to display on the panel.
        // Users can switch between these types.
        types: {
            auto: true,
            pedestrian: true,
            // Add the “taxi” icon
            // to the panel.
            taxi: true
        }
    });

    control.routePanel.state.set({
        // Use the route with the taxi
        // button by default.
        type: "taxi",
        from: '16 Lva Tolstogo, Moscow',
        to: 'Cheryomushki metro station'
    });
});
</script>  
Copied to clipboard

You can try out an interactive example in the sandbox.

Setting the panel size and position

You can set the routing panel size and where to place it on the map (for example, you can pin it to the upper-right corner of the map). Settings are listed in the reference guide.

Note that you can also customize the behavior of the panel, such as whether it will automatically get the focus when added to the map (the autofocus option).

The position and behavior settings for the panel are configured in the options field:

// Get a reference to the control.
var control = myMap.controls.get('routePanelControl');

control.options.set({
    // For the full list of options, see the reference guide.   
    maxWidth: '180px',
    float: 'right'
});

/*
// Alternative method for configure panel settings: 
// via the control.RoutePanel constructor when creating the panel. 
var routePanelControl = new ymaps.control.RoutePanel({
    options: {
        maxWidth: '180px', 
        float: 'right'
    }
});

// Add the panel to the map.
// Note: don't forget to delete 'routePanelControl'
// from the map's controls option.
myMap.controls.add(routePanelControl);
*/
Copied to clipboard
View the complete example code
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
ymaps.ready(function () {
    var myMap = new ymaps.Map('map', {
        center: [55.75, 37.57],
        zoom: 9,
        controls: ['routePanelControl']
    });
   
    // Get a reference to the control.
    var control = myMap.controls.get('routePanelControl');
    control.options.set({
        // For a list of all settings, see the reference guide.   
        maxWidth: '180px',
        float: 'right'
    });
});
</script>
Copied to clipboard

For solutions to other common problems, see the FAQ section.

Customizing the appearance of the route

You can use the API to change the appearance of a route. For example, you can set the color, width, or type of route paths, and set custom icons for placemarks.

Use the multiRouter.MultiRoute object to change the route's appearance. First get a reference to this object and then set the appearance using the set() method.

Getting information about a created route

Information about created routes is stored in a multiroute. To get a reference to this object, use the getRouteAsync() method:

// Get a reference to the panel.
var control = myMap.controls.get('routePanelControl');
  
// Get a multiroute.
var multiRoutePromise = control.routePanel.getRouteAsync();
Copied to clipboard

The getRouteAsync() method returns a Promise that is resolved by the multiRouter.MultiRoute object or dismissed with an error message. The multiroute will contain references to the created routes.

The following example shows how to get information about an active route: length, travel time, and information about closed sections of road:

multiRoutePromise.then(function(multiRoute) {
    // Subscribe to the multiroute update event.
    multiRoute.model.events.add('requestsuccess', function() {
        // Get a reference to the active route.
        var activeRoute = multiRoute.getActiveRoute();
        // When the panel is added to the map, it
        // creates a route with an initially empty geometry. 
        // When the user selects the start and ending points,
        // the route is recalculated with a non-empty geometry.
        // In order to avoid errors, we must add a check
        // to make sure that the route is not empty.
        if (activeRoute) {
            // Output information about the active route.
            console.log("Distance: " + activeRoute.properties.get("distance").text);
            console.log("Travel time: " + activeRoute.properties.get("duration").text);
        }
    });
}, function (err) {
  console.log(err); 
});  
Copied to clipboard

You can also use the multiRouter.MultiRoute object to change the appearance of the route (for example, change the line color or width):

multiRoute.options.set({
    // Color of the starting point placemark.
    wayPointStartIconFillColor: "#B3B3B3",
    // Color of the ending point placemark.
    wayPointFinishIconFillColor: "blue",     
    // Appearance of lines (for all routes).
    // To set the appearance of lines in the active route,
    // use the 'routeActive' prefix.
    routeStrokeColor: "00FF00"
});   
Copied to clipboard
View the complete example code
<meta charset="utf-8">
<script src="https://api-maps.yandex.ru/2.1/?lang=en_US" type="text/javascript"></script>
<div id="map" style="width:450px;height:300px"></div>

<script type="text/javascript">
// This example shows how to get information about a created route
// and change its appearance.

ymaps.ready(function () {
  var myMap = new ymaps.Map('map', {
      center: [55.753994, 37.622093],
      zoom: 9,
      // Add the routing panel to the map.
      controls: ['routePanelControl']
  });

  // Get a reference to the panel.
  var control = myMap.controls.get('routePanelControl');
  
  // Get an object that describes the created routes.
  var multiRoutePromise = control.routePanel.getRouteAsync();
  multiRoutePromise.then(function(multiRoute) {
    //  Subscribe to the event of receiving route data from the server.
    multiRoute.model.events.add('requestsuccess', function() {
      // Reference to the active route.
      var activeRoute = multiRoute.getActiveRoute();
      if (activeRoute) {
        // Output information about the active route.
        console.log("Distance: " + activeRoute.properties.get("distance").text);
        console.log("Travel time: " + activeRoute.properties.get("duration").text);
      }
    });
    multiRoute.options.set({
      // Color for the starting point icon.
      wayPointStartIconFillColor: "#B3B3B3",
      // Color for the ending point icon.
      wayPointFinishIconFillColor: "blue", 
      // Line appearance (for all routes).
      routeStrokeColor: "00FF00"
    });  
  }, function (err) {
    console.log(err); 
  });
});
</script>  
Copied to clipboard

To see how to get route segments and waypoints, go to Working with routes programmatically.

Solving typical tasks

How do I set a route for three or more points?

The routing panel allows you to set routes with only two points. To build more complex routes, use the multiRouter.MultiRoute class.

How can I set a route from a user's location?

To determine the user's location, use the geolocation.get() method. The method works asynchronously. It returns a Promise object, which is resolved by the GeoObjectCollection collection. The collection contains the coordinates and address of the user's current location.

var myMap = new ymaps.Map('map', {
    center: [55.751574, 37.573856],
    zoom: 9,
    controls: ['routePanelControl']
});
// Get a reference to the routing panel.
var control = myMap.controls.get('routePanelControl');
    
// Detect the user's location.
var location = ymaps.geolocation.get();
// The geolocation.get() method returns a Promise, which
// is resolved by GeoObjectCollection.
// A reference to this collection is available in the res.geoObjects field.
location.then(function (res) {
    // Get the address of the user's location.
    var userTextLocation = res.geoObjects.get(0).properties.get('text');
    control.routePanel.state.set({
        // Set the user's location as the starting point 
        // of the route.
        from: userTextLocation,
        // Address of the ending point.
        to: '16 Lva Tolstogo Moscow'
    });
});
Copied to clipboard
How can I hide labels on route markers?

To hide labels, disable the reverseGeocoding option. However, if you programmatically set route points, they must be set using coordinates.

The reverseGeocoding option is a flag that allows the API to perform reverse geocoding. This means that for points that are set using coordinates, the API sends requests to the Geocoder to determine their address from the coordinates. The received address is automatically displayed in labels as well as in the text field in the panel.

If you disable the reverseGeocoding option, reverse geocoding will not be used and labels will be hidden.

var myMap = new ymaps.Map('map', {
    center: [55.751574, 37.573856],
    zoom: 9,
    controls: ['routePanelControl']
});

// Get a reference to the
// routing panel.
var control = myMap.controls.get('routePanelControl');

control.routePanel.options.set({
    reverseGeocoding: false
});

control.routePanel.state.set({
    from: [55.734470, 37.58000],
    to: [55.734336, 37.51218]
});
Copied to clipboard
How do I set my own icon for route markers?

Example:

var myMap = new ymaps.Map('map', {
    center: [55.751574, 37.573856],
    zoom: 9,
    controls: ['routePanelControl']
});
// Get a reference to the route panel.
var control = myMap.controls.get('routePanelControl');

// Get a multiroute.
var multiRoutePromise = control.routePanel.getRouteAsync();

multiRoutePromise.then(function(multiRoute) {
  // Change the route appearance.
  // All options are listed in the reference guide.
  multiRoute.options.set({
    // Set a custom image
    // for the ending point.
    wayPointFinishIconLayout: "default#image",
    wayPointFinishIconImageHref: "images/sokolniki.png",
    wayPointFinishIconImageSize: [30, 30],
    wayPointFinishIconImageOffset: [-15, -15],
  });    
}, function (err) {
  console.log(err); 
});
Copied to clipboard
How do I set a custom route balloon layout?

See the example.

How can I disable the ability for users to set and change route points?

To prevent users from changing the route points on the map, set the toEnabled and fromEnabled options to false:

var myMap = new ymaps.Map('map', {
    center: [55.751574, 37.573856],
    zoom: 9,
    controls: ['routePanelControl']
});

// Get a reference to the routing panel.
var control = myMap.controls.get('routePanelControl');

// Set the states for the routing panel.
control.routePanel.state.set({
    // Flag that prevents users from changing
    // the address of the starting point in the text box.
    fromEnabled: false,
    // Flag that prevents users from changing
    // the address of the ending point in the text box.
    toEnabled: false,
    from: 'Tushinskaya ulitsa',
    to: '16 Lva Tolstogo Moscow'
    });
});
Copied to clipboard
I need to calculate the cost of delivery based on a route. How can I do this?

Take a look at the interactive example in the sandbox: Calculating delivery costs.

How do I disable auto focus on the panel?

To disable auto focus on the panel, use the autofocus option:

var myMap = new ymaps.Map('map', {
    center: [55.751574, 37.573856],
    zoom: 9,
    controls: ['routePanelControl']
});

var control = myMap.controls.get('routePanelControl');

control.options.set({
    autofocus: false
});
Copied to clipboard
How can I set a route that accounts for traffic?

The routing panel sets routes with traffic allowances by default. You can't disable traffic allowances at this time.

How do I programmatically reverse the route points?

Use the switchPoints() method to reverse the route points.

var control = myMap.controls.get ('routePanelControl');
// Set the route points.
control.routePanel.state.set({
    from: 'Tushinskaya ulitsa',
    to: '16 Lva Tolstogo Moscow',});// Reverse the points.control.routePanel.switchPoints();
Copied to clipboard

You can try out an interactive example in the sandbox.

How can I hide the button that reverses the starting and ending points of the route?

To hide the button, set the allowSwitch option to false:

var myMap = new ymaps.Map('map', {
    center: [55.753994, 37.622093],
    zoom: 9,
    controls: ['routePanelControl']
});

// Get a reference to the routing panel.
var control = myMap.controls.get('routePanelControl');
  
control.routePanel.options.set({
    // All the options are listed in the reference guide.
    allowSwitch: false 
}); 
Copied to clipboard
How do I set the panel title?
var myMap = new ymaps.Map('map', {
    center: [55.753994, 37.622093],
    zoom: 9,
    controls: ['routePanelControl']
});

// Get a reference to the routing panel.
var control = myMap.controls.get('routePanelControl');
    
control.options.set({
    // All the options are listed in the reference guide.
    // Set the panel title.
    title: 'Panel title',
    // Enable displaying the title.
    showHeader: true
});  
Copied to clipboard

Take a look at example in the sandbox.