Обзор
TSP API позволяет решить задачу коммивояжёра (TSP/VRP): построить кратчайший по времени или расстоянию маршрут обхода указанных точек. Для обхода точек можно указать как одного курьера, так и нескольких. Если указано несколько курьеров, маршрут будет разделён между ними наиболее оптимальным способом (некоторые курьеры могут быть исключены, если использование меньшего числа курьеров будет оптимальнее).
Для маршрута можно указать до 4000 точек и до 200 курьеров.
Получение ключа доступа
-
Зарегистрируйтесь в личном кабинете Менеджер Платформы.
-
Создайте демо-ключ или купите подписку для доступа к API. Подробнее о стоимости сервиса см. в разделе Тарифы.
Подробнее о работе с ключами и подписками см. в документации личного кабинета.
Пример задачи
Доставить груз со склада до трёх точек со следующими условиями:
- используется один курьер с грузоподъёмностью до 2000 кг;
- в каждую точку нужно доставить по 800 кг груза;
- курьер начинает и заканчивает путь на складе;
- склад и все точки доступны для посещения с 7:00 до 15:00.
Точки для посещения отмечены на карте. Чтобы посмотреть параметры каждой точки, наведите курсор на соответствующий маркер.
TSP API решает задачу коммивояжёра в асинхронном режиме. Чтобы построить маршрут (порядок прохождения точек):
- Отправьте запрос, чтобы создать задачу на построение маршрута.
- Периодически проверяйте статус задачи, пока не завершится расчёт маршрута.
- Получите готовый маршрут после завершения задачи.
Подробнее о параметрах из запросов ниже см. в Справочнике API.
TSP API предлагает наиболее оптимальный порядок прохождения указанных точек с учётом всех особенностей дорожной ситуации. Чтобы получить детальный маршрут проезда или прохода, используйте Routing API после получения решения от TSP API.
1. Создание задачи
Чтобы создать задачу на построение маршрута, отправьте POST-запрос на endpoint /logistics/vrp/2.0.0/create. В строке запроса укажите ваш ключ API в качестве значения параметра key:
https://routing.api.2gis.com/logistics/vrp/2.0.0/create?key=API_KEY
Координаты точек маршрута, количество курьеров и другие параметры передайте в виде JSON в теле запроса. Например, чтобы задать параметры обхода из примера задачи:
-
Перечислите все точки для посещения в массиве
waypointsи укажите параметры:id(обязательный): идентификатор точки.point(обязательный): координаты точки (lat,lon) и её расположение относительно дороги (type).type: тип точки (delivery,pickupилиagent).service_duration_s: продолжительность работы курьера в точке (в секундах).depot_ids: массив идентификаторов складов, с которых курьеры могут забрать заказ.time_windows: временные окна.shipment_size: размер груза.
{
"waypoints": [
{
"id": "1",
"point": { "lat": 55.708272, "lon": 37.46326, "type": "stop" },
"type": "delivery",
"service_duration_s": 0,
"depot_ids": ["0"],
"time_windows": [
{
"time_window": "07:00-15:00",
"hard_time_window": "07:00-15:00"
}
],
"shipment_size": { "weight_kg": 800 }
}
]
} -
Перечислите курьеров в массиве
agentsи укажите параметры:id(обязательный): идентификатор курьера.capacity: грузоподъёмность курьера.travel_time_multiplier: коэффициент скорости движения.cost: стоимость работы курьера.start_at: идентификатор склада, из которого курьер начинает маршрут.finish_at: идентификатор склада, в который курьер возвращается.
{
"agents": [
{
"id": "1",
"capacity": { "weight_kg": 2000 },
"travel_time_multiplier": 1.0,
"cost": {
"fixed": 3000,
"hour": 100,
"km": 8
},
"start_at": "0",
"finish_at": "0"
}
]
} -
(Опционально) Перечислите склады в массиве
depots:id: идентификатор склада.point: координаты склада с указанием типа.service_duration_s: время обслуживания на складе.time_window: временное окно работы склада (time_window,hard_time_window).
{
"depots": [
{
"id": "0",
"point": {
"lat": 55.734157,
"lon": 37.589346,
"type": "stop"
},
"service_duration_s": 0,
"time_window": {
"time_window": "07:00-15:00",
"hard_time_window": "07:00-15:00"
}
}
]
} -
(Опционально) Укажите параметры маршрута в объекте
options:route_type: тип маршрута (например,"jam"— с учётом пробок).routing_type: способ передвижения (например,"driving").date: дата маршрута в форматеYYYY-MM-DD.time_zone: часовой пояс (например,"Europe/Moscow").solver_time_limit_s: ограничение времени на решение задачи (в секундах).need_altitudes: нужно ли учитывать высоты (trueилиfalse).
{
"options": {
"route_type": "jam",
"routing_type": "driving",
"date": "2021-02-19",
"time_zone": "Europe/Moscow",
"solver_time_limit_s": 60,
"need_altitudes": false
}
}
Пример запроса
curl --location --request POST 'https://routing.api.2gis.com/logistics/vrp/2.0.0/create?key=API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"waypoints": [
{
"id": "1",
"point": {
"lat": 55.708272,
"lon": 37.46326,
"type": "stop"
},
"type": "delivery",
"service_duration_s": 0,
"depot_ids": [
"0"
],
"time_windows": [
{
"time_window": "07:00-15:00",
"hard_time_window": "07:00-15:00"
}
],
"shipment_size": {
"weight_kg": 800
}
},
{
"id": "2",
"point": {
"lat": 55.705352,
"lon": 37.461495,
"type": "stop"
},
"type": "delivery",
"service_duration_s": 0,
"depot_ids": [
"0"
],
"time_windows": [
{
"time_window": "07:00-15:00",
"hard_time_window": "07:00-15:00"
}
],
"shipment_size": {
"weight_kg": 800
}
},
{
"id": "3",
"point": {
"lat": 55.704175,
"lon": 37.471526,
"type": "stop"
},
"type": "delivery",
"service_duration_s": 0,
"depot_ids": [
"0"
],
"time_windows": [
{
"time_window": "07:00-15:00",
"hard_time_window": "07:00-15:00"
}
],
"shipment_size": {
"weight_kg": 800
}
}
],
"agents": [
{
"id": "1",
"capacity": {
"weight_kg": 2000
},
"travel_time_multiplier": 1.0,
"cost": {
"fixed": 3000,
"hour": 100,
"km": 8
},
"start_at": "0",
"finish_at": "0"
}
],
"depots": [
{
"id": "0",
"point": {
"lat": 55.734157,
"lon": 37.589346,
"type": "stop"
},
"service_duration_s": 0,
"time_window": {
"time_window": "07:00-15:00",
"hard_time_window": "07:00-15:00"
}
}
],
"options": {
"route_type": "jam",
"routing_type": "driving",
"date": "2021-02-19",
"time_zone": "Europe/Moscow",
"solver_time_limit_s": 60,
"need_altitudes": false
}
}'
Запрос вернёт информацию о созданной задаче, включая её идентификатор (task_id), который нужно будет использовать для проверки статуса:
{
"task_id": "dcabb3f6188935187d54088556238b83",
"status": {
"status": "Run",
"queued": "2026-04-20T11:44:14.906+00:00",
"started": null,
"matrix_downloaded": null,
"calculated": null,
"completed": null
},
"result": null
}
Ограничения
Запрос не будет выполнен, если:
- начальная или конечная точка курьера была исключена из маршрута;
- время выполнения запроса не входит в рабочее время ни одного из курьеров.
2. Проверка статуса задачи
Чтобы проверить статус задачи, отправьте GET-запрос на endpoint /logistics/vrp/2.0.0/status. В строке запроса укажите два параметра:
task_id— идентификатор задачи;key— ваш ключ API.
curl --location --request GET 'https://routing.api.2gis.com/logistics/vrp/2.0.0/status?task_id=dcabb3f6188935187d54088556238b83&key=API_KEY'
Если задача в процессе обработки, запрос вернёт тот же ответ, что и при создании задачи (поле status будет содержать значение "Run"):
{
"task_id": "dcabb3f6188935187d54088556238b83",
"status": {
"status": "Run",
"queued": "2026-04-20T11:44:14.906+00:00",
"started": null,
"matrix_downloaded": null,
"calculated": null,
"completed": null
},
"result": null
}
Если задача завершена, тело ответа будет содержать следующие данные:
-
status: одно из следующих значений:Done— маршрут успешно построен.Partial— маршрут построен, но из него были исключены точки или курьеры.Fail— при построении маршрута возникла ошибка.
-
queued: время постановки задачи в очередь в формате ISO 8601. -
started: время начала обработки. -
matrix_downloaded: время завершения загрузки матрицы достижимости (расстояний и времени в пути между всеми возможными парами точек из задачи). -
calculated: время завершения расчёта. -
completed: время завершения задачи.
{
"task_id": "dcabb3f6188935187d54088556238b83",
"status": {
"status": "Done",
"queued": "2026-04-20T11:44:14.906+00:00",
"started": "2026-04-20T11:44:14.906+00:00",
"matrix_downloaded": "2026-04-20T11:44:15.094+00:00",
"calculated": "2026-04-20T11:44:15.144+00:00",
"completed": "2026-04-20T11:44:15.144+00:00"
}
}
3. Получение решения
Решение задачи содержится в блоках result.metrics и result.routes. Исключённые точки и курьеры содержатся в полях result.dropped_waypoints и result.dropped_agents.
Пример ответа
{
"result": {
"metrics": {
"number_of_routes": 2,
"used_agents": 1,
"dropped_waypoints_count": 0,
"max_agent_runs": 2,
"total_duration_s": 3897,
"total_service_duration_s": 0,
"total_early_count": 0,
"total_early_duration_s": 0,
"total_distance_m": 55501
},
"options": {
"routing_type": "driving",
"route_type": "jam",
"date": "2021-02-19",
"time_zone": "Europe/Moscow",
"need_altitudes": false,
"solver_time_limit_s": 60
},
"routes": [
{
"agent_id": "1",
"run_number": 0,
"duration_s": 931,
"distance_m": 13606,
"route": [
{
"arrival_time": "2021-02-19T07:00:00+03:00",
"departure_time": "2021-02-19T07:00:00+03:00",
"node": {
"type": "depot",
"value": { "depot_id": "0", "delivery_to": "2" }
},
"service_start_time": "2021-02-19T07:00:00+03:00",
"waiting_duration_s": 0,
"transit_duration_s": 0,
"transit_distance_m": 0
},
{
"arrival_time": "2021-02-19T07:00:00+03:00",
"departure_time": "2021-02-19T07:00:00+03:00",
"node": {
"type": "depot",
"value": { "depot_id": "0", "delivery_to": "1" }
},
"service_start_time": "2021-02-19T07:00:00+03:00",
"waiting_duration_s": 0,
"transit_duration_s": 0,
"transit_distance_m": 0
},
{
"arrival_time": "2021-02-19T07:15:31+03:00",
"departure_time": "2021-02-19T07:15:31+03:00",
"node": {
"type": "waypoint",
"value": { "waypoint_id": "1", "picked_up_from": "0" }
},
"service_start_time": "2021-02-19T07:15:31+03:00",
"waiting_duration_s": 0,
"transit_duration_s": 931,
"transit_distance_m": 13606
}
]
},
{
"agent_id": "1",
"run_number": 1,
"duration_s": 2966,
"distance_m": 41895,
"route": [
{
"arrival_time": "2021-02-19T07:30:16+03:00",
"departure_time": "2021-02-19T07:30:16+03:00",
"node": {
"type": "depot",
"value": { "depot_id": "0", "delivery_to": "3" }
},
"service_start_time": "2021-02-19T07:30:16+03:00",
"waiting_duration_s": 0,
"transit_duration_s": 885,
"transit_distance_m": 13546
},
{
"arrival_time": "2021-02-19T07:46:12+03:00",
"departure_time": "2021-02-19T07:46:12+03:00",
"node": {
"type": "waypoint",
"value": { "waypoint_id": "3", "picked_up_from": "0" }
},
"service_start_time": "2021-02-19T07:46:12+03:00",
"waiting_duration_s": 0,
"transit_duration_s": 956,
"transit_distance_m": 13441
},
{
"arrival_time": "2021-02-19T07:49:48+03:00",
"departure_time": "2021-02-19T07:49:48+03:00",
"node": {
"type": "waypoint",
"value": { "waypoint_id": "2", "picked_up_from": "0" }
},
"service_start_time": "2021-02-19T07:49:48+03:00",
"waiting_duration_s": 0,
"transit_duration_s": 216,
"transit_distance_m": 1376
},
{
"arrival_time": "2021-02-19T08:04:57+03:00",
"departure_time": "2021-02-19T08:04:57+03:00",
"node": {
"type": "agent",
"value": { "waypoint_id": "0" }
},
"service_start_time": "2021-02-19T08:04:57+03:00",
"waiting_duration_s": 0,
"transit_duration_s": 909,
"transit_distance_m": 13532
}
]
}
],
"dropped_waypoints": [],
"dropped_agents": []
}
}
Рассчитанный маршрут движения курьеров отмечен на карте.
Тарифы
- Стоимость сервиса рассчитывается исходя из объёма решаемой задачи: количества точек для посещения, умноженного на количество курьеров. Например, если в задаче 5 точек и 2 курьера, оплачиваются 10 расчётов.
- Актуальную стоимость и лимиты см. в разделе Тарифы.
Варианты размещения
- Облако: все методы TSP API доступны через публичные endpoint-ы 2ГИС.
- On-Premise: все методы TSP API доступны при установке API-платформы 2ГИС в закрытом контуре. Подробнее см. в разделе API-платформа для сервера.
Помощь
-
Если у вас возникли вопросы при работе с API, задайте их AI-ассистенту (в правом нижнем углу cайта), воспользуйтесь поиском по документации или отправьте электронное письмо на api@2gis.ru.
-
Если вы хотите обсудить возможности API или его интеграцию с вашим продуктом, обратитесь к менеджеру.