Overview

Routing API helps you plot one or multiple routes on the map for transport or walking. An interactive example below shows building a route for a car:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        <title>Urbi Routing API</title>
        <meta name="description" content="Routing API 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.27280, 25.19918],
                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') {
                    // Display selected points on the, 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, 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.

You can also work with Routing API in the playground (no authorization needed).

Key features

Route types

by car
by taxi
by bicycle
by scooter
by motorcycle
by truck (with territory limitations)
for emergency services (with territory limitations)
on foot

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.

Route building parameters

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

Real-time traffic (with regular updates) or statistically predicted congestion.
Road closures (considered by default, can be forcibly ignored).
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

Route points

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.
Up to 50 pairs of points when building multiple routes in one request (using intermediate points is not supported).
Building routes using intermediate points is only available within city limits.
Building routes using intermediate points is not supported for bicycle routes.

Truck routing

Truck routing is available in the following countries:

Azerbaijan
Armenia
Belarus
Georgia
Kazakhstan
Russia
Uzbekistan
United Arab Emirates

When constructing a truck route, you can also exclude dirt and toll roads.

Emergency services routing

Routing for emergency services is available in the following countries:

Oman
Saudi Arabia
United Arab Emirates

Tariffs

When building a route for one set of points (including intermediate points), the number of requests is charged. Building alternative routes is not charged additionally.
When building multiple routes for a set of point pairs, calculations for each pair of points are charged. For example, if you specify 5 arrays of point pairs (points field) in one request, 5 calculations are charged.

What's next?

Get started.
Examples of using Routing API.
API Reference.