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 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)

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

<!DOCTYPE html>
<html lang="en">
    <head>
        <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">
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script src="https://unpkg.com/@2gis/mapgl-directions@^2/dist/directions.js"></script>
    </body>
</html>

// API key can be used on jsfiddle.net only!
// You can get more info on https://docs.2gis.com/

const map = new mapgl.Map('container', {
    center: [55.31878, 25.23584],
    zoom: 13,
    key: 'bfd8bbca-8abf-11ea-b033-5fa57aae2de7',
});
const directions = new mapgl.Directions(map, {
    // This key can be used for demo purpose only!
    // You can get your own key on http://partner.api.2gis.ru/
    directionsApiKey: 'rubfpx2151',
});
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;
    directions.clear();
    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
        markers.push(
            new mapgl.Marker(map, {
                coordinates: coords,
                icon: 'https://docs.2gis.com/img/dotMarker.svg',
            }),
        );
    }
    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) {
        directions.carRoute({
            points: [firstPoint, secondPoint],
        });
        markers.forEach((m) => {
            m.destroy();
        });
        resetButton.disabled = false;
        resetButton.textContent = buttonText[1];
    }
});

html,
body,
#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;
}

<!DOCTYPE html>
<html lang="en">
    <head>
        <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" />
        <style>
            html,
            body,
            #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;
            }
        </style>
    </head>
    <body>
        <div id="container"></div>
        <script src="https://mapgl.2gis.com/api/js/v1"></script>
        <script src="https://unpkg.com/@2gis/mapgl-directions@^2/dist/directions.js"></script>
        <script>
            const map = new mapgl.Map('container', {
                center: [55.31878, 25.23584],
                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 http://partner.api.2gis.ru/
                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;
                directions.clear();
                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
                    markers.push(
                        new mapgl.Marker(map, {
                            coordinates: coords,
                            icon: 'https://docs.2gis.com/img/dotMarker.svg',
                        }),
                    );
                }

                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) {
                    directions.carRoute({
                        points: [firstPoint, secondPoint],
                    });
                    markers.forEach((m) => {
                        m.destroy();
                    });
                    resetButton.disabled = false;
                    resetButton.textContent = buttonText[1];
                }
            });
        </script>
    </body>
</html>

Getting an access key

Usage of this API requires an API key. To obtain the key, fill out the form at dev.2gis.com/order.

Request example

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.

https://catalog.api.2gis.com/carrouting/6.0.0/global?key=API_KEY

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 'https://catalog.api.2gis.com/carrouting/6.0.0/global?key=API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
   "locale": "en",
   "points": [
       {
           "type": "pedo",
           "x": 82.93057,
           "y": 54.943207
       },
       {
           "type": "pedo",
           "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.

Response example

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": "pedo",
                "x": 82.93057,
                "y": 54.943207
            },
            {
                "type": "pedo",
                "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"
}

Route types

Shortest route in time

By default, the server returns the shortest car route in time using current traffic data. To build a specific type of route, set the type parameter in the request.

{
    "points": [...],
    "type": "jam" // car route using current traffic data
}

Instead of current traffic data, you can build a route using statistical traffic data. To do this, specify the statistic route type and the required timestamp as Unix time in the utc parameter.

{
    "points": [...],
    "type": "statistic", // car route using statistical traffic data...
    "utc": 1606826131    // ...as of 1 December 2020, 12:00 UTC
}

Shortest route in distance

To build the shortest route in distance, even if it is not optimal due to traffic jams, specify the shortest route type.

{
    "points": [...],
    "type": "shortest" // car route ignoring traffic
}

Public transport lanes

You can also include public transport lanes when building a car route, which can be useful for taxi and bus routes. To do this, add the "taxi_" prefix to the required route type: taxi_jam, taxi_statistic, taxi_shortest.

{
    "points": [...],
    "type": "taxi_jam" // taxi route using current traffic data
}

Pedestrian route

To build a pedestrian route, specify the pedestrian route type.

{
    "points": [...],
    "type": "pedestrian" // pedestrian route
}

Bicycle route

To build a bicycle route, specify the bicycle route type.

{
    "points": [...],
    "type": "bicycle" // bicycle route
}

By default, bicycle routes include stairways, overground crossings, underground crossings, and car roads. You can exclude them from the route by using the filters parameter (see Avoiding road types).

Route points

Start and end points

If the starting or ending point of a car route is not located on a road, a path will be added to the route connecting it with the nearest road. You can adjust this by using one of two point types for the start or end point:

pedo - add a pedestrian path avoiding all obstacles such as buildings
stop - add a simple straight path that ignores all obstacles

"points": [
   {
       "type": "pedo", // pedestrian path from the starting point to the nearest road
       "x": 82.93057,
       "y": 54.943207
   },
   {
       "type": "stop", // straight path from road to end point
       "x": 82.945039,
       "y": 55.033879
   }
]

For any type of route, you can set several start and end points, which can be useful, for example, if a building has multiple entrances or exits. When multiple points are specified, only one of them (the most convenient) will be used to build an optimal route.

To separate start and end points in the points array, you can use the start parameter or add intermediate points to the route (see the next section).

"points": [
   {
       "type": "stop",
       "x": 82.93057,
       "y": 54.943207,
       "start": true
   },
   {
       "type": "stop",
       "x": 82.93856,
       "y": 54.943112,
       "start": true
   },
   {
       "type": "stop",
       "x": 82.945039,
       "y": 55.033879
   }
]

Intermediate points

You can add intermediate points to any route by using the pref point type. The total number of route points must not exceed 10.

"points": [
   {
       "type": "pedo",
       "x": 82.93057,
       "y": 54.943207
   },
   {
       "type": "pref",
       "x": 82.941984,
       "y": 54.974563
   },
   {
       "type": "pedo",
       "x": 82.945039,
       "y": 55.033879
   }
]

Avoiding road types

When building a route, you can exclude certain types of roads, such as dirt roads and toll roads (for a car route) or stairways and overground/underground crossings (for a bicycle route). To do this, use the filters parameter.

For example, to exclude dirt roads from a car route, specify the value "dirt_road":

{
    "points": [...],
    "filters": ["dirt_road"] // exclude dirt roads from the route
}

To exclude stairways, overground crossings, underground crossings, and car roads from a bicycle route, specify the following array of values:

{
    "points": [...],
    "type": "bicycle",
    "filters": [
        "ban_stairway",  // exclude stairways
        "ban_over",      // exclude overground and underground crossings
        "ban_car_road",  // exclude car roads
    ]
}

If the route without the specified road types is too long or impossible to build, parts of the resulting route may still include the excluded road types.

You can also exclude certain types of roads from a pedestrian route. For a complete list of possible values, see API Reference.

Excluding areas

To exclude specific areas from the route, use the exclude parameter.

Areas can be specified as circles, polygons, or thick lines. To specify an area, use the following parameters:

type - shape of the area (circle, polygon, or line)
points - coordinates of the area
extent - area size in meters (radius of a circle, width of a line)

{
    "points": [...],
    "exclude": [
        // circle with a radius of 100 meters
        {
            "type": "point",
            "points": [
                {
                    "x": 82.03057,
                    "y": 54.043207
                }
            ],
            "extent": 100
        },
        // line with a width of 1 kilometer
        {
            "type": "polyline",
            "points": [
                {
                    "x": 82.13057,
                    "y": 54.143207
                },
                {
                    "x": 82.23057,
                    "y": 54.243207
                }
            ],
            "extent": 1000
        }
    ]
}

For each area, you can additionally specify the severity parameter, which determines how strictly the area should be avoided: if possible (soft) or always (hard).

{
    "points": [...],
    "exclude": [
        // exclude a polygonal area
        {
            "type": "polygon",
            "points": [
                {"x": 55.28770929, "y": 25.22069944},
                {"x": 55.28976922, "y": 25.25656786},
                {"x": 55.33302789, "y": 25.25687836},
                {"x": 55.33096795, "y": 25.22007825},
                {"x": 55.28770929, "y": 25.22069944}
            ],
            "severity": "hard"
        }
    ]
}