# TSP API — Vietmap API Playground

> Reorders a list of stops into the shortest route for a single vehicle.

The TSP API (travelling salesman) reorders a list of stops so the total distance is shortest, for one vehicle. The start and end can be fixed, or the route can return to the start; the result gives the optimal visiting order and the path. With several vehicles, capacities or time windows, use VRP.

What it is for:
- Ordering one courier’s deliveries for the day.
- Visit plans for field sales.
- Collection or inspection rounds.
- Multi-stop day trips.

- Interactive page: https://tools.vietmap.vn/playground/en/tsp
- Endpoint: `GET /api/tsp/v4` on `https://maps.vietmap.vn`
- Official documentation: https://maps.vietmap.vn/docs/map-api/tsp-version/tsp-v4/
- API key: every request needs the `apikey` parameter. Samples use `YOUR_API_KEY` as the placeholder — when integrating, read the key from an environment variable (e.g. `VIETMAP_API_KEY`). Get a key at https://maps.vietmap.vn/console-v2/consumers
- Error codes: `401` wrong API key · `403` key restricted to another domain/IP · `423` API not enabled for the key's consumer, or out of credit (body contains "exceeded credit") · `429` rate limit exceeded.

## Code samples

_This is an example request with sample parameters; open the interactive page to change them and run it for real._

### cURL

```bash
curl 'https://maps.vietmap.vn/api/tsp/v4?apikey=YOUR_API_KEY&point=10.7768,106.7009&point=10.80189,106.7066&point=10.7725,106.6828&point=10.80159,106.68982&point=10.7839,106.6911&point=10.79628,106.70592&points_encoded=false&vehicle=car&roundtrip=false&sources=first&destinations=any'
```

### JavaScript

```javascript
// In production, read the key from an environment variable instead.
const API_KEY = "YOUR_API_KEY";

const params = new URLSearchParams([
  ["apikey", API_KEY],
  ["point", "10.7768,106.7009"],
  ["point", "10.80189,106.7066"],
  ["point", "10.7725,106.6828"],
  ["point", "10.80159,106.68982"],
  ["point", "10.7839,106.6911"],
  ["point", "10.79628,106.70592"],
  ["points_encoded", "false"],
  ["vehicle", "car"],
  ["roundtrip", "false"],
  ["sources", "first"],
  ["destinations", "any"],
]);

const response = await fetch(`https://maps.vietmap.vn/api/tsp/v4?${params}`);
if (!response.ok) {
  throw new Error(`Vietmap ${response.status}: ${await response.text()}`);
}
const data = await response.json();
console.log(data);
```

### Python

```python
import requests

# In production, read the key from an environment variable instead.
API_KEY = "YOUR_API_KEY"

params = [
    ("apikey", API_KEY),
    ("point", "10.7768,106.7009"),
    ("point", "10.80189,106.7066"),
    ("point", "10.7725,106.6828"),
    ("point", "10.80159,106.68982"),
    ("point", "10.7839,106.6911"),
    ("point", "10.79628,106.70592"),
    ("points_encoded", "false"),
    ("vehicle", "car"),
    ("roundtrip", "false"),
    ("sources", "first"),
    ("destinations", "any"),
]

response = requests.get("https://maps.vietmap.vn/api/tsp/v4", params=params, timeout=30)
response.raise_for_status()
print(response.json())
```

### URL

```text
https://maps.vietmap.vn/api/tsp/v4?apikey=YOUR_API_KEY&point=10.7768,106.7009&point=10.80189,106.7066&point=10.7725,106.6828&point=10.80159,106.68982&point=10.7839,106.6911&point=10.79628,106.70592&points_encoded=false&vehicle=car&roundtrip=false&sources=first&destinations=any
```

## AI prompt

A ready-made prompt for a coding assistant (ChatGPT, Claude, Copilot…) to write the integration:

````text
I need to integrate Vietmap's TSP API v4 into my application.

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

Here is a sample request that works in the Vietmap API Playground:

GET https://maps.vietmap.vn/api/tsp/v4?apikey=YOUR_API_KEY&point=10.7768,106.7009&point=10.80189,106.7066&point=10.7725,106.6828&point=10.80159,106.68982&point=10.7839,106.6911&point=10.79628,106.70592&points_encoded=false&vehicle=car&roundtrip=false&sources=first&destinations=any

Parameters in use:
- point = 10.7768,106.7009
- point = 10.80189,106.7066
- point = 10.7725,106.6828
- point = 10.80159,106.68982
- point = 10.7839,106.6911
- point = 10.79628,106.70592
- points_encoded = false
- vehicle = car
- roundtrip = false
- sources = first
- destinations = any

Write code in [my language / framework] that calls this API, with these requirements:
1. Read the API key from the VIETMAP_API_KEY environment variable; never hard-code it.
2. Send the parameters in the query string exactly as in the sample; repeated parameters (such as `point`) must keep their order.
3. Handle Vietmap's HTTP errors:
   - 401: the API key is wrong or revoked.
   - 403: the key is restricted to a domain / IP that does not match.
   - 423: the API is not enabled for the key's consumer, OR the account is out of credit — tell them apart by the response body ("exceeded credit" means out of credit).
   - 429: rate limit exceeded — retry with increasing backoff.
4. Set a request timeout, and define types (type / interface / dataclass) for the response.

If unsure about a field name, look it up in the documentation linked above instead of guessing.
````

## Reopen this exact request in the Playground

https://tools.vietmap.vn/playground/en/tsp?point=10.7768,106.7009&point=10.80189,106.7066&point=10.7725,106.6828&point=10.80159,106.68982&point=10.7839,106.6911&point=10.79628,106.70592&vehicle=car&sources=first