Directions API

Directions API is deprecated. Use Routing API to build car, truck, bicycle, or pedestrian routes through one service.

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

Directions API supports the following types of routes:

a fastest car route considering current or statistical traffic data
a shortest car route in distance
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:

altitude information (height above sea level and elevation changes)
information about special points on the route (for example, start of a toll road)

<!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: [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 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

To start using navigation services, get an access key for Routing API:

Sign in to the Platform Manager.
Create a demo key or purchase an access key for using API: see the Access keys instruction.
See the Routing API documentation to start using the service.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.

Request example

Note

Examples below are for the deprecated Directions API. If you have switched to Routing API, refer to the corresponding documentation.

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://routing.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://routing.api.2gis.com/carrouting/6.0.0/global?key=API_KEY' \
 --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.

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": "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"
}