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 = ['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];
    }
});

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 = ['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>

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

Для доступа к 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" // велосипедный маршрут
}

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

Типы точек

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

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

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.

Например, чтобы исключить грунтовые дороги из автомобильного маршрута, нужно указать значение "dirt_road":

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

Чтобы исключить лестницы, подземные/надземные переходы и автомобильные дороги из велосипедного маршрута, нужно указать следующий массив значений:

{
    "points": [...],
    "type": "bicycle",
    "filters": [
        "ban_stairway",  // исключить лестницы
        "ban_over",      // исключить подземные и надземные переходы
        "ban_car_road",  // исключить автомобильные дороги
    ]
}

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

Также можно исключить некоторые типы дорог из пешеходного маршрута. Полный список возможных значений можно найти в Справочнике 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"
        }
    ]
}