# Traveling Salesman Problem

Source: https://maps.vietmap.vn/docs/map-api/tsp-version/tsp-v4/

Traveling Salesman Problem (TSP) v4
=======

 [![TSP]][TSP]
 [TSP]: https://maps.vietmap.vn/docs/assets/TSP-jpg.webp


* * *
TSP v4 takes a list of points and returns the route for **one** vehicle through all of them with the lowest total driving time, with geometry and turn-by-turn instructions. Times come from the VIETMAP road network for the given `vehicle` (one-way streets and restrictions included). By default the route returns to the first point; change that with `roundtrip`, `sources` and `destinations`. For more than one vehicle use [VRP](https://maps.vietmap.vn/docs/map-api/vrp/).

!!! tip "Try it in the Playground"
    Call TSP v4 with real data, no code required: **[Open Playground](https://tools.vietmap.vn/playground/tsp)**

!!! tip "AI Agent Integration :sparkles: NEW"
    Download the optimized doc for AI agent integration (Matrix + TSP + VRP): **<a href="/docs/assets/agents/logistics.txt" download="logistics.txt">Logistics Agent Doc</a>** · Machine-readable schema: **[OpenAPI 3.1](/docs/openapi.json)**

Or try it in [Postman](https://app.getpostman.com/run-collection/10912981-433d17b2-76d7-416e-beb2-468b9682b7a7?action=collection%2Ffork).

## TSP or VRP?

| Your situation | API |
| --- | --- |
| **One** vehicle, many stops — just tell me the order | **TSP v4** (this page) |
| **Several** vehicles — decide who takes what, then order each route | [VRP](https://maps.vietmap.vn/docs/map-api/vrp/) |
| I want raw travel times and will plan myself | [Distance Matrix](https://maps.vietmap.vn/docs/map-api/matrix-version/matrix-v4/) |
| I know the order already, I need the road path | [Routing](https://maps.vietmap.vn/docs/map-api/route-version/route-v4/) |

## Common setups

| Situation | Parameters |
| --- | --- |
| Start and end at the depot | `roundtrip=true` (default) |
| Start at the depot, end anywhere | `roundtrip=false&sources=first` |
| End at the last `point` you sent | `roundtrip=false&destinations=last` |
| Need opening hours or load limits | use [VRP](https://maps.vietmap.vn/docs/map-api/vrp/) (`time_windows`, `capacity`) |

## Costing

A TSP request is billed as one transaction per stop — a 20-stop tour costs 20 transactions. See [How Pricing Works](https://maps.vietmap.vn/docs/map-api/console/request-to-transaction/).


## URL

```
https://maps.vietmap.vn/api/tsp/v4?apikey={your-apikey}&point={point}&point={point}&point={point}&points_encoded={points_encoded}&vehicle={vehicle}&roundtrip={roundtrip}&destinations={destinations}&sources={sources}
```


Method 
-----------
**GET**

### Migrate from v3 → v4
- The endpoint changes from `/api/tsp/v3` to `/api/tsp/v4`.
- TSP v4 runs on the same v4 routing engine as [Route v4](https://maps.vietmap.vn/docs/map-api/route-version/route-v4/), so results are consistent with v4 routes.
- The request parameters and the response format are unchanged, so migrating is a matter of updating the URL.

See the previous version docs: [TSP v3](https://maps.vietmap.vn/docs/map-api/tsp-version/tsp-v3/).

## Parameters


|Parameter|Type|Required|Default|Description|
|--- |--- |--- |--- |--- |
|apikey|string|yes|none|API key provided by VIETMAP for your account. [Register here](https://maps.vietmap.vn/console-v2/register)|
|point|array string|yes|none|The points for which the route should be calculated. Format: [latitude,longitude]. Specify at least an origin and a destination. Via points are possible. The maximum number depends on your plan.|
|points_encoded|boolean|no|true|Allows changing the encoding of location data in the response. The default is polyline encoding, which is compact but requires special client code to unpack. Set this parameter to false to switch the encoding to simple coordinate pairs like [lon,lat]. See the description of the response format for more information.|
|vehicle|string|no|car|Enum: `car`, `motorcycle`, `truck`, `container`. The vehicle profile for which the route should be calculated.|
|roundtrip|boolean|no|true|`true` (default): the route returns to the start point. `false`: open route; where it starts and ends is controlled by `sources`/`destinations`.|
|sources|string|no|any|`any` (default): the solver picks the start point. `first`: the route must start at the first `point` sent.|
|destinations|string|no|any|`any` (default): the solver picks the end point. `last`: the route must end at the last `point` sent (use with `roundtrip=false`).|

## Example


**Input**
```swift
https://maps.vietmap.vn/api/tsp/v4?apikey={your-apikey}&point=10.79628438955497,106.70592293472612&point=10.801891047584164,106.70660958023404&point=10.801595962927763,106.6898296806408&points_encoded=true&vehicle=motorcycle&roundtrip=true
```

[:material-play-circle: Run this example on the Playground](https://tools.vietmap.vn/playground/tsp?point=10.79628438955497,106.70592293472612&point=10.801891047584164,106.70660958023404&point=10.801595962927763,106.6898296806408&vehicle=motorcycle&roundtrip=true){ .md-button .md-button--primary }

**Response**
```json
{
    "license": "vietmap",
    "code": "OK",
    "messages": null,
    "paths": [
        {
            "distance": 7720.5,
            "weight": 1022.8,
            "time": 1022800,
            "transfers": 0,
            "points_encoded": true,
            "bbox": [
                106.68973,
                10.79352,
                106.71098,
                10.80307
            ],
            "points": "}s{`Ac_hjSIP[r@KTuAxCOb@QVuAoAi@g@w@u@oCmC_BgBm@}@QUcB{C}@qBMYs@{B]}A_@kBSkCIo@oABFbAHtAPtAPpAbApDXv@Rj@dAzBT^dAdBqA^e@Jo@F{BLCcAAEICq@@p@AHB@DBbAzBMn@Gd@KpA_@LRZh@dAvAv@z@pI`I[t@u@vA|@h@LJDLa@jL?`AF^gBVeF~@GZuAb@sARgDr@uHfBa@PGBd@xAF\\?RGz@WnEk@~HSzCUlDH?bB?TnAJbAH|@?VBz@?j@?JGJGXGf@?n@Db@H~BjCn@?B?JAFI?}BCAcAI_CEc@?o@Fg@FYFK?K?k@C{@?WI}@KcAUoAdAAz@CP?`A?b@?z@CbAI\\E^GHAJ?VClAGbBGPA`ACLAv@CH?~BOj@C~@Al@Ar@C@kADKbDJ~@Bh@LGk@Bo@H[T[TOPGNCNA`AFlA@REVSFIFQBYGkA@{@Ig@[_AA}B@y@Hq@BO@g@EmAAWCg@Ac@BwAX_DHs@H{@DUP_@No@Be@?KEMGd@GJIDE?k@i@Q?WJGG}AqA?a@mAoAeDcDQQUUyEmEPWNc@tAyCJUZs@HQ",
            "instructions": [
                {
                    "distance": 192,
                    "heading": 0,
                    "sign": 0,
                    "interval": [
                        0,
                        6
                    ],
                    "text": "Tiếp tục theo Đường Nguyễn Cửu Vân",
                    "time": 25900,
                    "street_name": "Đường Nguyễn Cửu Vân",
                    "last_heading": null
                },
                {
                    "distance": 0,
                    "heading": 0,
                    "sign": 4,
                    "interval": [
                        201,
                        201
                    ],
                    "text": "Đích đến",
                    "time": 0,
                    "street_name": "Đường Nguyễn Cửu Vân",
                    "last_heading": null
                }
            ],
            "snapped_waypoints": "}s{`Ac_hjS}`@{CVphB"
        }
    ]
}
```

Response truncated; middle elements omitted.

### Response description
| Field            | Type   | Description                                                                      |
|------------------|--------|----------------------------------------------------------------------------------|
| license          | string | The type of license for the map data.                                            |
| code             | string | A code indicating the status of the response. Details at [Status Code Values](#status-code-values)            |
| messages         | null   | Messages associated with the response, if any.                                   |
| paths            | array  | An array containing route information, such as distance, time, and instructions. |

Each object in the `paths` array contains the following fields:

| Field             | Type    | Description                                                                       |
|-------------------|---------|-----------------------------------------------------------------------------------|
| distance          | float   | The total distance of the route (in meters).                                     |
| weight            | float   | The weight of the route.                                                         |
| time              | integer | The total time required to travel the route (in milliseconds).                    |
| transfers         | integer | The number of transfers during the route.                                         |
| points_encoded    | boolean | Indicates whether the points are encoded.                                         |
| bbox              | array   | The bounding box of the route.                                                    |
| points            | string  | Encoded points along the route.                                                   |
| instructions      | array   | An array containing step-by-step instructions for navigating the route.           |
| snapped_waypoints | string  | Snapped waypoints along the route.                                                |

Each object in the `instructions` array contains the following fields:

| Field         | Type    | Description                                                |
|---------------|---------|------------------------------------------------------------|
| distance      | float   | The distance of the instruction.                           |
| heading       | integer | The heading direction of the instruction.                  |
| sign          | integer | The sign indicating the action to take (e.g., turn left).  |
| interval      | array   | The first and last index (of the `points` list) of the route section covered by this instruction. |
| text          | string  | The textual instruction for navigating.                    |
| time          | integer | The time required to complete the instruction.            |
| street_name   | string  | The name of the street for the instruction.               |
| last_heading  | null    | The last heading direction for the instruction.           |

### Status Code Values

- `OK`: The request was successful and the response contains valid data.
- `INVALID_REQUEST`: The request parameters failed validation. Details about the validation errors are provided in the messages field of the response.
- `OVER_DAILY_LIMIT`: The daily request limit for your API key has been exceeded. No further requests will be processed until the limit resets.
- `MAX_POINTS_EXCEED`: The number of points in the request URL exceeds the allowed maximum for your plan. Reduce the number of points and try again.
- `ERROR_UNKNOWN`: An unexpected error occurred while processing the API request. Please check the messages field for more information or contact support if the issue persists.
- `ZERO_RESULTS`: No viable route was found between the requested waypoints.

!!! tip "Try it with your own data"
    Enter your own addresses, coordinates or parameters and see the result on a map, with a cURL command to copy: **[Open TSP v4 on the Playground](https://tools.vietmap.vn/playground/tsp)**

## Frequently asked questions

### When do I get `ZERO_RESULTS`?

When no road path connects all the `point` values sent for the selected `vehicle`. Check the coordinate order first (latitude, then longitude); if you are using `vehicle=truck` or `container`, call again with `vehicle=car` to see whether a point sits on a road closed to trucks.