Directions API

The Directions API allows you to plot a route on the map from one point to another. The Directions API can build the following types of routes:

a route for a car with information about traffic jams based on the real-time or statistical data
a route for a car avoiding toll and dirt roads, if this option was chosen when building the route
a pedestrian route with information about crosswalks and obstacles
a route from point A to point B with up to 10 intermediate stops, including start and end points

How It Works

Requests are made using the POST method, all required parameters should be passed in the JSON format. The responses are also generated in the JSON format.

The request takes the coordinates of the route points. You will receive the geometry and length of the route and estimated travel time in response. All request and response parameters are listed in the API Reference.

To plot a route select the start and end points on the map.

<!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@^1/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 controlsHtml = `<button id="reset">Сбросить точки</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();
});
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();
        });
    }
});

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: 12px;
    cursor: pointer;
}

<!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: 12px;
                cursor: pointer;
            }
        </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@^1/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 controlsHtml = `<button id="reset">Сбросить точки</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();
            });

            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();
                    });
                }
            });
        </script>
    </body>
</html>

Example of Request

To retrieve route data make a POST request to https://catalog.api.2gis.com/carrouting/6.0.0/global?key=YOUR_KEY with Content-Type application/json.

The request takes the following parameters:

key=YOUR_KEY — your API key

{
    "locale": "en",
    "point_a_name": "Source",
    "point_b_name": "Target",
    "points": [
        {
            "type": "pedo",
            "x": 82.93057,
            "y": 54.943207
        },
        {
            "object_id": "141476222741292",
            "type": "pedo",
            "x": 82.945039,
            "y": 55.033879
        }
    ],
    "type": "jam"
}

Example of Response

{
    "query": {
      "locale": "en",
      "point_a_name": "Source",
      "point_b_name": "Target",
      "points": [],
      "type": "jam"
    },
    "result": [
      {
        "algorithm": "including traffic jams",
        "begin_pedestrian_path": {...},
        "end_pedestrian_path": {...},
        "filter_road_types": [...],
        "id": "1805336109018823561",
        "maneuvers": [...],
        "route_id": "em9.n3/carrouting/1588235082.031",
        "total_distance": 15153,
        "total_duration": 2204,
        "type": "carrouting",
        "ui_total_distance": {},
        "ui_total_duration": "36 min",
        "waypoints": [...]
      }
    ],
    "type": "string"
}

Getting Started

Fill in the application form to get your key.
Learn about the request and response formats.