Directions API

Directions API позволяет проложить маршрут на карте из одной точки в другую. Directions API прокладывает следующие маршруты:

автомобильный маршрут с учётом пробок в реальном времени или на основе данных статистики по пробкам;
автомобильный маршрут в объезд платных и грунтовых дорог, если пользователь выбрал такую настройку;
пеший маршрут с учётом пешеходных переходов и в обход препятствий;
через несколько точек — до 10 с учётом конечной и начальной точек.

Как это работает

Запросы осуществляются методом POST, все необходимые параметры передаются в формате JSON. Ответы формируются в формате JSON.

В запросе передаются координаты точек маршрута. В ответ приходят геометрия и длина маршрута и время в пути. Все параметры запроса и ответа приведены в описании 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@^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>

Пример запроса

Данные можно получить с помощью POST-запроса на URL https://catalog.api.2gis.com/carrouting/6.0.0/global?key=YOUR_KEY и payload'а с Content-Type application/json.

В запросе используются следующие параметры:

key=YOUR_KEY — ваш ключ API.

{
    "locale": "ru",
    "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"
}

Пример ответа

{
    "query": {
      "locale": "ru",
      "point_a_name": "Source",
      "point_b_name": "Target",
      "points": [],
      "type": "jam"
    },
    "result": [
      {
        "algorithm": "с учётом пробок",
        "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 мин",
        "waypoints": [...]
      }
    ],
    "type": "string"
}

Начало работы

Получите ключ доступа к API. Для этого заполните анкету.
Посмотрите все параметры форматов запроса и ответа.