Directions API

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

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

Чтобы построить маршрут для грузового транспорта, используйте Truck Directions 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@^2/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 buttonText = ['Выберите две точки на карте', 'Сбросить точки'];
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];
    }
});

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;
}

<!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: [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 buttonText = ['Выберите две точки на карте', 'Сбросить точки'];

            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>

Получение ключа

Для доступа к API нужен специальный ключ. Чтобы его получить, заполните форму по адресу dev.2gis.ru/order.

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

Чтобы проложить маршрут, нужно отправить POST-запрос на endpoint /carrouting/6.0.0/global. В строке запроса укажите ваш ключ API в качестве значения параметра key.

https://catalog.api.2gis.com/carrouting/6.0.0/global?key=API_KEY

Координаты точек маршрута и другие параметры нужно передать в виде JSON в теле запроса.

Например, чтобы построить автомобильный маршрут из точки A в точку B с учётом текущих пробок, можно отправить следующий запрос:

curl --request POST \
 --url 'https://catalog.api.2gis.com/carrouting/6.0.0/global?key=API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
   "points": [
       {
           "type": "pedo",
           "x": 82.93057,
           "y": 54.943207
       },
       {
           "type": "pedo",
           "x": 82.945039,
           "y": 55.033879
       }
   ]
}'

Массив points содержит координаты точек маршрута (x - долгота, y - широта). Первый элемент в массиве является точкой отправления.

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

Запрос вернет объект, включающий длину маршрута в метрах (total_distance), время в пути в секундах (total_duration), список манёвров (maneuvers) и другие поля. Информацию о каждом поле можно посмотреть в Справочнике API.

{
    "query": {
        "points": [
            {
                "type": "pedo",
                "x": 82.93057,
                "y": 54.943207
            },
            {
                "type": "pedo",
                "x": 82.945039,
                "y": 55.033879
            }
        ]
    },
    "result": [
        {
            "algorithm": "с учётом пробок",
            "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 мин",
            "waypoints": [...]
        }
    ],
    "type": "result"
}

Типы маршрутов

Кратчайший по времени

По умолчанию прокладывается кратчайший по времени автомобильный маршрут с учётом текущих пробок. Чтобы указать тип маршрута явно, нужно добавить в запрос поле type.

{
    "points": [...],
    "type": "jam" // автомобильный маршрут по текущим пробкам
}

Вместо текущих пробок можно использовать статистическую информацию по пробкам. Для этого нужно указать тип маршрута statistic и нужную дату-время в виде Unix-времени в поле utc.

{
    "points": [...],
    "type": "statistic", // автомобильный маршрут на основе статистических данных по пробкам...
    "utc": 1606826131    // ...на 1 декабря 2020 года, 12 часов UTC
}

Кратчайший по расстоянию

Чтобы построить самый короткий маршрут, даже если он не является оптимальным по времени из-за пробок, нужно указать тип shortest.

{
    "points": [...],
    "type": "shortest" // автомобильный маршрут без учета пробок
}

С учётом полос общественного транспорта

Также можно строить маршруты с учётом полос общественного транспорта (удобно для такси и автобусов). Для этого нужно к выбранному типу маршрута добавить префикс "taxi_": taxi_jam, taxi_statistic, taxi_shortest.

{
    "points": [...],
    "type": "taxi_jam" // автомобильный маршрут по текущим пробкам, включающий полосы общественного транспорта
}

Пешеходный

Чтобы проложить пешеходный маршрут, нужно указать тип pedestrian.

{
    "points": [...],
    "type": "pedestrian" // пешеходный маршрут
}

Велосипедный

Чтобы проложить велосипедный маршрут, нужно указать тип bicycle.

{
    "points": [...],
    "type": "bicycle" // велосипедный маршрут
}

Типы точек

Начальные и конечные точки

Если начальная или конечная точка автомобильного маршрута расположена не на дороге, то в маршрут будет добавлен путь, соединяющий её с ближайшей дорогой. Для этого можно использовать два типа точек:

pedo - будет добавлен путь с обходом препятствий, таких как здания (пешеходный);
stop - будет добавлен прямой путь, игнорирующий препятствия.

"points": [
   {
       "type": "pedo", // пешеходный путь от начальной точки до ближайшей дороги
       "x": 82.93057,
       "y": 54.943207
   },
   {
       "type": "stop", // прямой путь от дороги до конечной точки
       "x": 82.945039,
       "y": 55.033879
   }
]

Для любого типа маршрута можно указать несколько начальных и конечных точек. Это может быть удобно в тех случаях, когда у здания есть несколько входов и выходов. При указании нескольких точек будет построен оптимальный маршрут от одной из начальных точек до одной из конечных.

Чтобы отделить начальные точки от конечных в массиве points, можно использовать параметр start или добавить промежуточные точки (см. следующий раздел).

"points": [
   {
       "type": "stop",
       "x": 82.93057,
       "y": 54.943207,
       "start": true
   },
   {
       "type": "stop",
       "x": 82.93856,
       "y": 54.943112,
       "start": true
   },
   {
       "type": "stop",
       "x": 82.945039,
       "y": 55.033879
   }
]

Промежуточные точки

В любой маршрут можно добавить промежуточные точки, указав тип pref. Общее количество точек в маршруте не должно превышать 10.

"points": [
   {
       "type": "pedo",
       "x": 82.93057,
       "y": 54.943207
   },
   {
       "type": "pref",
       "x": 82.941984,
       "y": 54.974563
   },
   {
       "type": "pedo",
       "x": 82.945039,
       "y": 55.033879
   }
]

Исключение типов дорог

При построении маршрута можно исключить определенные типы дорог, такие как грунтовые или платные. Чтобы это сделать, нужно указать в запросе поле filters.

{
    "points": [...],
    "filters": ["dirt_road"] // исключить из маршрута грунтовые дороги
}

Список возможных значений для поля filters можно посмотреть в Справочнике API.

Исключение областей

В запросе можно указать области, которые будут избегаться при построении маршрута. Для этого используется поле exclude.

Область можно указать в виде круга, многоугольника или толстой линии. Для описания области используется три параметра:

type - форма исключаемой области (круг, многоугольник или линия);
points - координаты области;
extent - размер области в метрах (радиус круга или ширина линии).

{
    "points": [...],
    "exclude": [
        // круг с радиусом 100 метров
        {
            "type": "point",
            "points": [
                {
                    "x": 82.03057,
                    "y": 54.043207
                }
            ],
            "extent": 100
        },
        // линия шириной 1000 метров
        {
            "type": "polyline",
            "points": [
                {
                    "x": 82.13057,
                    "y": 54.143207
                },
                {
                    "x": 82.23057,
                    "y": 54.243207
                }
            ],
            "extent": 1000
        }
    ]
}

Для каждой области можно дополнительно указать параметр severity - насколько строго нужно избегать выбранную область (soft - избегать по возможности; hard - избегать всегда).

{
    "points": [...],
    "exclude": [
        // исключить область в виде многоугольника
        {
            "type": "polygon",
            "points": [
                {"x": 55.28770929, "y": 25.22069944},
                {"x": 55.28976922, "y": 25.25656786},
                {"x": 55.33302789, "y": 25.25687836},
                {"x": 55.33096795, "y": 25.22007825},
                {"x": 55.28770929, "y": 25.22069944}
            ],
            "severity": "hard"
        }
    ]
}