Navigation | TSP API | Overview | 2GIS Documentation
TSP API

TSP API

TSP API allows you to solve the traveling salesman problem (TSP/VRP) - building a shortest route in time or distance to pass through the specified points. You can specify one or several couriers. When using multiple couriers, the route will be divided into several parts, and each courier will receive its own unique sub-route.

You can specify up to 4000 points and up to 200 couriers for a route.

Usage of this API requires an API key. To obtain the key, fill out the form at dev.2gis.com/order.

To build a route, you need to:

  1. Create a route building task.
  2. Periodically check the status of the task until the route calculation is complete.
  3. Get the calculated route when the task is complete.

To create a task, you need to send a POST request to the /logistics/vrp/1.0/create endpoint. Specify your API key as the value of the key parameter in the query string.

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

Route point coordinates, number of couriers and other parameters must be sent as a JSON string in the request body.

For example, to create a task of passing through six points with two couriers, you can send the following request:

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": 1
    }
  ]
}'

The waypoints array contains the coordinates of the points to be traversed. Additionally, you need to set a custom identifier for each point (waypoint_id) to link the points in this array with the points in the calculated route and with the points used by the couriers.

List of couriers should be specified in the agents parameter. For each courier, you need to set a custom identifier (agent_id) and specify the identifier of the starting point (start_waypoint_id). Additionally, you can specify the identifier of the point at which the courier must end their route (finish_waypoint_id).

Above request will return information about the created task, including the task ID (task_id), which should be used to check the task status.

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

To check the status of the task, you need to send a GET request to the /logistics/vrp/1.0/status endpoint. You need to specify two parameters in the query string:

  • task_id - task ID
  • key - your API key
curl --request GET "http://catalog.api.2gis.com/logistics/vrp/1.0/status?key=API_KEY&task_id=551348e2e29223ee046c715ffb115934"

If the task is still being processed, the request will return the same response as when the task was initially created (the status field will contain the value "Run"):

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

If the task is completed, the status field will contain one of the following values:

  • Done - the route was successfully built;
  • Partial - the route was built, but one or more points were excluded from it;
  • Fail - an error occurred when building the route.

In case of Done and Partial, the response will contain a link to the solution file with the calculated route, and the time it took to build the route. Detailed information about each field can be found in the API Reference.

{
    // task ID
    "task_id": "551348e2e29223ee046c715ffb115934",
    // task status
    "status": "Done",
    "urls": {
        // link to the solution file
        "url_vrp_solution": "http://s3.2gis.one/navi-vrp-bucket/551348e2e29223ee046c715ffb115934-sln.json",
        // link to the file with the list of excluded points (this file will be empty if the task status is not "Partial")
        "url_excluded": "http://s3.2gis.one/navi-vrp-bucket/551348e2e29223ee046c715ffb115934-excluded.json"
    },
    // time taken to build the route (see API Reference for more info)
    "dm_queue": 1,
    "dm": 4,
    "vrp_queue": 1,
    "vrp": 1
}

Solution file contains a JSON object with a list of routes for each courier and the total travel time.

{
    "routes": [
        {
            // courier ID
            "agent_id": 0,
            // courier route duration in seconds
            "duration": 2720,
            // list of IDs of points for the courier to pass through
            "points": [0, 5, 3]
        },
        {
            "agent_id": 1,
            "duration": 1734,
            "points": [1, 4, 2]
        }
    ],
    // total travel time in seconds
    "summary_duration": 4454
}

The file contains a list of IDs of points that were excluded from the route (for example, they are located too far relative to the other points).

[6, 7]

By default, the server returns the shortest car route in time using current traffic data. To build a specific type of route, set the type parameter in the request.

{
    "waypoints": [...],
    "agents": [...],
    "type": "jam" // car route using current traffic data
}

Instead of current traffic data, you can build a route using statistical traffic data. To do this, specify the statistics route type and the required date and time in RFC 3339 format as the start_time parameter.

{
    "waypoints": [...],
    "agents": [...],
    "type": "statistics", // car route using statistical traffic data...
    "start_time": "2020-05-15T15:52:01Z"    // ...as of 15 May 2020, 15:52:01 UTC
}

To build the shortest route in distance, even if it is not optimal due to traffic jams, specify the shortest route type.

{
    "waypoints": [...],
    "agents": [...],
    "type": "shortest" // car route ignoring traffic
}

You can also include public transport lanes when building a car route, which can be useful for taxi and bus routes. To do this, add the mode parameter with the value taxi.

{
    "waypoints": [...],
    "agents": [...],
    "mode": "taxi", // car route including public transport lanes...
    "type": "shortest" // ...and ignoring traffic
}

To build a pedestrian route, use the mode parameter with the value walking.

{
    "waypoints": [...],
    "agents": [...],
    "mode": "walking" // pedestrian route
}

To build a bicycle route, use the mode parameter with the value bicycle.

{
    "waypoints": [...],
    "agents": [...],
    "mode": "bicycle" // bicycle route
}

When building a route, you can exclude certain types of roads, such as toll roads or dirt roads, using the filters parameter. For more information on using this parameter, see the corresponding section of Directions API.