Навигация | TSP API | Обзор | 2GIS Documentation

TSP API

TSP API позволяет решить задачу коммивояжёра (TSP/VRP) - построить кратчайший по времени или расстоянию маршрут обхода указанных точек. Для обхода точек можно указать как одного курьера, так и нескольких. При использовании нескольких курьеров маршрут будет разбит на несколько частей и каждый курьер получит свой уникальный подмаршрут.

Для маршрута можно указать до 4000 точек и до 200 курьеров.

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

Чтобы построить маршрут, нужно:

  1. Создать задачу на построение маршрута.
  2. Периодически проверять статус задачи, пока не завершится расчёт маршрута.
  3. Получить готовый маршрут после завершения задачи.

Для создания задачи на построение маршрута нужно отправить POST-запрос на endpoint /logistics/vrp/1.0/create. В строке запроса укажите ваш ключ API в качестве значения параметра key.

https://catalog.api.2gis.com/logistics/vrp/1.0/create?key=API_KEY

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

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

curl --request POST \
 --url "https://catalog.api.2gis.com/logistics/vrp/1.0/create?key=API_KEY" \
 --header 'Content-Type: application/json' \
 --data '{
  "waypoints": [
    {
      "waypoint_id": 0,
      "point": {
        "lat": 55.72011298880675,
        "lon": 37.4449720376539
      }
    },
    {
      "waypoint_id": 1,
      "point": {
        "lat": 55.76851601909724,
        "lon": 37.86501600000758
      }
    },
    {
      "waypoint_id": 2,
      "point": {
        "lat": 55.7085452,
        "lon": 37.9031455
      }
    },
    {
      "waypoint_id": 3,
      "point": {
        "lat": 55.622219,
        "lon": 37.608992
      }
    },
    {
      "waypoint_id": 4,
      "point": {
        "lat": 55.76565171838069,
        "lon": 37.83871081320576
      }
    },
    {
      "waypoint_id": 5,
      "point": {
        "lat": 55.73938281238814,
        "lon": 37.48333351388388
      }
    }
  ],
  "agents": [
    {
      "agent_id": 0,
      "start_waypoint_id": 0
    },
    {
      "agent_id": 1,
      "start_waypoint_id": 0
    }
  ]
}'

Массив waypoints содержит координаты точек, которые нужно обойти. Для каждой точки дополнительно нужно задать произвольный идентификатор в виде числа (waypoint_id), чтобы было удобнее связывать точки в этом массиве с точками получившегося маршрута и теми точками, которые использует курьеры.

Список курьеров нужно указать в параметре agents. Для каждого курьера нужно задать идентификатор в виде числа (agent_id) и указать идентификатор отправной точки (start_waypoint_id). Дополнительно можно указать идентификатор точки, в которой курьер должен завершить движение (finish_waypoint_id).

Запрос вернёт информацию о созданной задаче, включая её идентификатор (task_id), который нужно будет использовать для проверки статуса.

{
    "task_id": "551348e2e29223ee046c715ffb115934",
    "status": "Run",
    "urls": null,
    "dm_queue": null,
    "dm": null,
    "vrp_queue": null,
    "vrp": null
}

Чтобы проверить статус задачи, нужно отправить GET-запрос на endpoint /logistics/vrp/1.0/status. В строке запроса нужно указать два параметра:

  • task_id - идентификатор задачи;
  • key - ваш ключ API.
curl --request GET "http://catalog.api.2gis.com/logistics/vrp/1.0/status?key=API_KEY&task_id=551348e2e29223ee046c715ffb115934"

Если задача в процессе обработки, то запрос вернёт тот же ответ, что и при создании задачи (поле status будет содержать значение "Run"):

{
    "task_id": "551348e2e29223ee046c715ffb115934",
    "status": "Run",
    "urls": null,
    "dm_queue": null,
    "dm": null,
    "vrp_queue": null,
    "vrp": null
}

Если задача завершена, то поле status будет содержать одно из следующих значений:

  • Done - маршрут успешно построен;
  • Partial - маршрут построен, но из него были исключены одна или несколько точек;
  • Fail - при построении маршрута возникла ошибка.

В случае Done и Partial ответ будет содержать ссылку на файл с решением и время, которое было потрачено на поиск решения. Подробную информацию о каждом поле можно найти в Справочнике API.

{
    // идентификатор задачи
    "task_id": "551348e2e29223ee046c715ffb115934",
    // статус задачи
    "status": "Done",
    "urls": {
        // ссылка на файл с решением
        "url_vrp_solution": "http://s3.2gis.one/navi-vrp-bucket/551348e2e29223ee046c715ffb115934-sln.json",
        // ссылка на файл со списком исключенных точек (файл будет пустым, если статус задачи не "Partial")
        "url_excluded": "http://s3.2gis.one/navi-vrp-bucket/551348e2e29223ee046c715ffb115934-excluded.json"
    },
    // набор полей, содержащих время, потраченное на поиск решения
    "dm_queue": 1,
    "dm": 4,
    "vrp_queue": 1,
    "vrp": 1
}

Файл с решением содержит JSON-объект, в котором указан список маршрутов для каждого курьера и общее время в пути.

{
    "routes": [
        {
            // идентификатор курьера
            "agent_id": 0,
            // продолжительность маршрута данного курьера (в секундах)
            "duration": 442,
            // идентификаторы точек для обхода курьером
            "points": [0, 5]
        },
        {
            "agent_id": 1,
            "duration": 5030,
            "points": [3, 2, 4, 1]
        }
    ],
    // общее время в пути всех курьеров (в секундах)
    "summary_duration": 5472
}

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

[6, 7]

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

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

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

{
    "waypoints": [...],
    "agents": [...],
    "type": "statistics", // автомобильный маршрут на основе статистических данных по пробкам...
    "start_time": "2020-05-15T15:52:01Z"    // ...на 15 мая 2020 года, 15:52:01 UTC
}

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

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

Также можно строить маршруты с учётом полос общественного транспорта (удобно для такси и автобусов). Для этого нужно добавить в запрос поле mode со значением taxi.

{
    "waypoints": [...],
    "agents": [...],
    "mode": "taxi", // автомобильный маршрут, включающий полосы общественного транспорта...
    "type": "shortest" // ...без учёта пробок
}

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

{
    "waypoints": [...],
    "agents": [...],
    "mode": "walking" // пешеходный маршрут
}

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

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

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