Truck Directions API

Воспользуйтесь Routing API, чтобы прокладывать автомобильные, грузовые, велосипедные или пешеходные маршруты через один сервис.

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

Truck Directions API при построении маршрута для грузового транспорта учитывает:

габариты и массу автомобиля;
максимально разрешённую массу на маршруте;
ограничения на движение с опасными и взрывчатыми грузами;
ограничения знаками 3.4 «Движение грузовых автомобилей запрещено» и 3.2 «Движение запрещено» в сочетании с табличками 8.4.1 «Вид транспортного средства», 8.11 «Ограничение разрешённой максимальной массы» (2,5 тонны ) и 8.3.1–8.3.2 «Направление действия».
пробки в реальном времени или статистику пробок;
грунтовые и платные дороги и предлагает маршрут в объезд таких дорог, если пользователь выбрал такую настройку.

Для каждого маршрута Truck Directions API может возвращать:

информацию о высоте маршрута над уровнем моря и изменении высоты на протяжении маршрута;
информацию о специальных точках на маршруте (например, начало платного участка дороги).

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

На видео представлен пример построения маршрута для грузового транспорта с учётом ограничений на габариты автомобиля.

На видео представлен пример построения маршрута для грузового автомобиля в объезд улиц, по которым запрещено движение грузового транспорта.

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

Для доступа к API нужен специальный ключ. Чтобы его получить:

Зарегистрируйтесь в личном кабинете Platform Manager.
Создайте демо-ключ (если вы еще не пользовались продуктами 2ГИС) или запросите боевой ключ по ссылке для связи с менеджером на вкладке Ключи API.

В личном кабинете вы также можете:

Просматривать информацию по своим уже созданным ключам: какие сервисы подключены, какой лимит задан по каждому из них, когда ключ будет деактивирован.
Задавать ограничения на ключ по HTTP-заголовкам или по IP и подсетям.
Изучать статистику распределения запросов по каждому ключу.

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

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

https://routing.api.2gis.com/truck/6.0.0/global?key=API_KEY

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

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

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

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

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

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

{
    "query": {
        "points": [
            {
                "type": "walking",
                "x": 82.93057,
                "y": 54.943207
            },
            {
                "type": "walking",
                "x": 82.945039,
                "y": 55.033879
            }
        ],
        "type": "truck_jam"
    },
    "result": [
        {
            "algorithm": "с учётом пробок",
            "begin_pedestrian_path": {...},
            "end_pedestrian_path": {...},
            "filter_road_types": [...],
            "id": "1805336109018823561",
            "maneuvers": [...],
            "route_id": "...",
            "total_distance": 15153,
            "total_duration": 2204,
            "type": "truckrouting",
            "ui_total_distance": {},
            "ui_total_duration": "36 мин",
            "waypoints": [...]
        }
    ],
    "type": "result"
}

Параметры грузового автомобиля

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

{
    "points": [...],
    "truck_params": {
        "max_perm_mass": 10,
        "mass": 9,
        "axle_load": 4,
        "height": 3.2,
        "width": 2.5,
        "length": 7,
        "dangerous_cargo": true,
        "explosive_cargo": true
    }
}

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

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

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

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

{
    "points": [...],
    "type": "truck_jam" // маршрут для грузового транспорта по текущим пробкам
}

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

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

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

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

{
    "points": [...],
    "type": "truck_shortest" // маршрут для грузового транспорта без учёта пробок
}

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

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

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

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

Информация о высоте

Чтобы получить информацию о высоте маршрута и её изменении на протяжении маршрута, нужно указать параметр need_altitudes.

{
    "points": [...],
    "need_altitudes": true
}

При указании этого параметра ответ будет содержать следующую информацию:

Суммарное увеличение и снижение высоты (в сантиметрах).
Максимальная и минимальная высота над уровнем моря (в сантиметрах).
Максимальный угол наклона.
Угол наклона и высота над уровнем моря для каждого сегмента маршрута.

{
    "altitudes_info": {
        // Суммарное увеличение высоты.
        "elevation_gain": 12440,
        // Суммарное снижение высоты.
        "elevation_loss": 11020,
        // Максимальная высота над уровнем моря.
        "max_altitude": 10700,
        // Минимальная высота над уровнем моря.
        "min_altitude": 6600,
        // Максимальный угол наклона.
        "max_road_angle": 8
    },
    "geometry": [
        {
            // Угол наклона.
            "angles": "LINESTRING(1, -1)",
            "color": "ignore",
            "length": 22,
            // Высота над уровнем моря (третье значение).
            "selection": "LINESTRING(82.930722 54.943655 9200, 82.930815 54.943650 9220, 82.930926 54.943640 9190)",
            "style": "normal"
        }
    ]
}

Специальные точки

В некоторых случаях ответ может содержать дополнительное поле route_points, в котором будут перечислены специальные типы точек, встречающиеся на маршруте. Например, если маршрут включает проезд по платной дороге, поле route_points будет содержать координаты начальной и конечной точек платного участка.

{
    "route_points": [
        {
            // Координаты точки.
            "coordinates": {
                "lat": 55.73942822546596,
                "lon": 37.37259908712576
            },
            // Расстояние от начала маршрута (в метрах).
            "distance": 746,
            // Тип специальной точки.
            "type": "TollRoadBegin"
        },
        {
            "coordinates": {
                "lat": 55.71525675255834,
                "lon": 37.31850882892307
            },
            "distance": 5784,
            "type": "TollRoadEnd"
        }
    ]
}