Overview

Routing API will help you plot one or multiple routes on a map for transport or walking.

Key features

Types of available routes:

Car
Taxi
Pedestrian
Bicycle
Truck
Emergency services

Routing for emergency services is available in the following regions: United Arab Emirates, Oman, and Saudi Arabia.

For each route, you can obtain:

Length, travel time, and full geometry.
Elevation change along the route.
Information about special points on the route, such as the start of a toll road.

You can consider the following parameters when constructing routes, depending on the selected transport type:

Real-time traffic or statistically predicted congestion.
Public transport lanes for taxis and emergency services.
Different road types.
Pedestrian crossings, stairways, and detours.
Exclusion of a specific area.
Weight, dimensions, and sign restrictions for trucks.

For more information about route parameters, see API Reference.

Limitations

Intermediate points

Constructing routes using waypoints is only available within city limits.
Up to 10 waypoints, including the start and finish points for cars and trucks.
Up to 5 waypoints, including the start and finish points for pedestrian routes.
Waypoint construction is not supported for bicycle routes.

Truck routing

Truck routing is available in the following countries:

Azerbaijan
Belarus
Kazakhstan
Kyrgyzstan
Uzbekistan
United Arab Emirates
Oman
Russia
Saudi Arabia
Uzbekistan
Ukraine

When constructing a truck route, it is also possible to exclude dirt and toll roads.

Example usage

To become familiar with Routing API, use the interactive example:

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

To edit the example code, select Source code, and then Edit on Codepen.

What's next?

Quick Start.
Examples of using Routing API.
API Reference.