Navigation | TSP API | Overview | 2GIS Documentation

TSP API

TSP/VRP API (Travelling salesman problem/Vehicle routing problem) позволяет решить задачу коммивояжёра — построить кратчайший по времени маршрут обхода указанных точек на карте для одного или нескольких курьеров.


Чтобы рассчитать задачу TSP/VRP, необходимо:

  1. Создать задачу методом POST с необходимыми параметрами в формате JSON. Ответ будет содержать идентификатор задачи также в формате JSON.
  2. Периодически опрашивать методом GET статус задачи, пока её статус не перейдет в детерменированное состояние, например "готова" или "ошибка"
  3. Когда задача будет рассчитана, то ответ на запрос GET будет также содержать ссылку на файл с решением в формате JSON.

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


Чтобы создать задачу, нужно отправить POST-запрос на endpoint /logistics/vrp/1.0/create. В запросе используются следующие параметры:

  • key=YOUR_KEY — ваш ключ API.
http://catalog.api.2gis.com/logistics/vrp/1.0/create?key=API_KEY

Набор точек для задания задачи нужно передать в виде JSON в теле запроса.

curl --request POST \
 --url "http://catalog.api.2gis.com/logistics/vrp/1.0/create?key=myapikey12345" \
 --header 'Content-Type: application/json' \
 --data '{
  "mode": "driving",
  "type": "jam",
  "start_time": "2021-04-26T07:05:30Z",
  "agents": [
    {
      "agent_id": 0,
      "start_waypoint_id": 0
    },
    {
      "agent_id": 1,
      "start_waypoint_id": 0
    }
  ],
  "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
      }
    }
  ]
}'

Запрос вернёт информацию о созданной задаче: идентификтор задачи, её статус и другую информацию.

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

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

  • key=YOUR_KEY — ваш ключ API.
  • task_id=TASK_ID — идентификатор задачи, полученный раннее.
curl --request GET  "http://catalog.api.2gis.com/logistics/vrp/1.0/status?key=YOUR_KEY&task_id=TASK_ID"

Если задача в процессе обработки:

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

Если задача рассчитана (статус в состоянии Done или Partial):

  • urls.url_vrp_solution - ссылка на файл в формате JSON с решением задачи
  • urls.url_excluded - ссылка на файл в формате JSON с точками, которые являются недостижимыми относительно всех остальных (файл будет пустым, ести статус задачи Done и не пустым, если статус Partial)
  • dm_queue - время ожидания расчета матрицы достижимости точек
  • dm - продолжительность расчета матрицы достижимости точек
  • vrp_queue - время ожидания расчета задачи коммивояжера
  • vrp - продолжительность расчета задачи коммивояжера
{
    "task_id": "551348e2e29223ee046c715ffb115934",
    "status": "Done",
    "urls": {
        "url_vrp_solution": "http://s3.2gis.one/navi-vrp-bucket/551348e2e29223ee046c715ffb115934-sln.json",
        "url_excluded": "http://s3.2gis.one/navi-vrp-bucket/551348e2e29223ee046c715ffb115934-excluded.json"
    },
    "dm_queue": 1,
    "dm": 4,
    "vrp_queue": 1,
    "vrp": 1
}
  • routes - массив маршрутов для агентов
  • agent_id - идентификатор агента
  • duration - продолжительность маршрута в секундах
  • points - массив идентификаторов точек для обхода соответствующим агентом
  • summary_duration - суммарное время всех маршрутов
{
    "routes": [
        {
            "agent_id": 0,
            "duration": 442,
            "points": [0, 5]
        },
        {
            "agent_id": 1,
            "duration": 5030,
            "points": [3, 2, 4, 1]
        }
    ],
    "summary_duration": 5472
}

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

[6, 7]