Navigation | Directions API | Overview | Urbi Documentation

Directions API

Directions API allows you to build a route from point A to point B.

Directions API supports the following types of routes:

  • an optimal car route considering current or statistical traffic conditions
  • a shortest possible car route without taking traffic conditions into account
  • a car route avoiding certain types of roads, like toll roads or dirt roads
  • a car route that includes public transport lanes (a taxi route)
  • a pedestrian route including crosswalks and avoiding obstacles
  • a pedestrian route inside buildings with floor plans
  • a bicycle route including pedestrian crossings and optionally avoiding stairways, overpasses, underpasses, and highways
  • a route with intermediate points (up to 10, including start and end point)

For each route, Directions API can additionally return the following information:

To build a route for a truck, use Truck Directions API.

<!DOCTYPE html>
<html lang="en">
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>2GIS Navi API</title>
        <meta name="description" content="Navi API directions example" />
            #container {
                margin: 0;
                width: 100%;
                height: 100%;
                overflow: hidden;
            #reset {
                padding: 4px 10px;
                background: #00a81f;
                border-radius: 4px;
                box-shadow: 0 1px 3px 0 rgba(38, 38, 38, 0.5);
                border: none;
                color: #fff;
                font-size: 13px;
                cursor: pointer;
            #reset:disabled {
                background: #f2f2f2;
                color: #6e6d6d;
                cursor: default;
        <div id="container"></div>
        <script src=""></script>
        <script src="^2/dist/directions.js"></script>
            const map = new mapgl.Map('container', {
                center: [37.668598, 55.76259],
                zoom: 13,
                key: 'Your API access key',

            const directions = new mapgl.Directions(map, {
                // This key can be used for demo purpose only!
                // You can get your own key on
                directionsApiKey: 'Your directions API access key',
            const markers = [];

            let firstPoint;
            let secondPoint;
            // A current selecting point
            let selecting = 'a';
            const buttonText = ['Choose two points on the map', 'Reset points'];

            const controlsHtml = `<button id="reset" disabled>${buttonText[0]}</button> `;
            new mapgl.Control(map, controlsHtml, {
                position: 'topLeft',
            const resetButton = document.getElementById('reset');

            resetButton.addEventListener('click', function() {
                selecting = 'a';
                firstPoint = undefined;
                secondPoint = undefined;
                this.disabled = true;
                this.textContent = buttonText[0];

            map.on('click', (e) => {
                const coords = e.lngLat;

                if (selecting != 'end') {
                    // Just to visualize selected points, before the route is done
                        new mapgl.Marker(map, {
                            coordinates: coords,
                            icon: '',

                if (selecting === 'a') {
                    firstPoint = coords;
                    selecting = 'b';
                } else if (selecting === 'b') {
                    secondPoint = coords;
                    selecting = 'end';

                // If all points are selected — we can draw the route
                if (firstPoint && secondPoint) {
                        points: [firstPoint, secondPoint],
                    markers.forEach((m) => {
                    resetButton.disabled = false;
                    resetButton.textContent = buttonText[1];

Usage of this API requires an API key. To obtain the key, fill out the form at

To calculate a route, send a POST request to the /carrouting/6.0.0/global endpoint. Specify your API key as the key parameter in the query string.

Coordinates for the route and other parameters must be sent as a JSON string in the request body.

For example, to build a car route from point A to point B considering the current traffic condition, you can send a request similar to the following:

curl --request POST \
 --url '' \
 --header 'Content-Type: application/json' \
 --data '{
   "locale": "en",
   "points": [
           "type": "walking",
           "x": 82.93057,
           "y": 54.943207
           "type": "walking",
           "x": 82.945039,
           "y": 55.033879

The points parameter is an array of route points (x is the longitude of a point; y is the latitude of a point). The first element of the array is the starting point.

The response will return an object containing the information about the calculated route: route length in meters (total_distance), travel time in seconds (total_duration), a list of maneuvers (maneuvers), and other fields. You can find information about each field in API Reference.

    "query": {
        "points": [
                "type": "walking",
                "x": 82.93057,
                "y": 54.943207
                "type": "walking",
                "x": 82.945039,
                "y": 55.033879
    "result": [
            "algorithm": "with traffic jams",
            "begin_pedestrian_path": {...},
            "end_pedestrian_path": {...},
            "filter_road_types": [...],
            "id": "1805336109018823561",
            "maneuvers": [...],
            "route_id": "...",
            "total_distance": 15153,
            "total_duration": 2204,
            "type": "carrouting",
            "ui_total_distance": {},
            "ui_total_duration": "36 min",
            "waypoints": [...]
    "type": "result"