Optimized route

Reorder a list of points to minimize total distance or total duration (traveling salesman problem).

The Optimized Routing endpoint reorders a list of points to compute the optimal tour — typically the delivery sequence that minimizes total distance or total duration. It’s a solution to the traveling salesman problem (TSP).

Endpoint

POST https://api.tmaps.tn/routing/optimized?api_key=YOUR_API_KEY

Parameters

JSON body

Param	Type	Requis	Défaut	Description
`origin`	object	oui	—	Starting point `{ lat, lng }`. Stays fixed in the optimized tour.
`waypoints`	array	oui	—	List of points `{ lat, lng }` to reorder (max 50).
`destination`	object	—	—	Fixed end point `{ lat, lng }`. If omitted, the tour ends at the last optimized waypoint.
`profile`	string	—	`driving`	Transport profile: `driving`, `walking`, `cycling`, `truck`.
`optimize`	string	—	`duration`	Optimization criterion: `duration` or `distance`.
`roundtrip`	boolean	—	`false`	If `true`, the tour returns to the origin.
`geometry`	string	—	`polyline`	Geometry format: `polyline` or `geojson`.
`steps`	boolean	—	`false`	If `true`, returns turn-by-turn instructions for each leg.

Advanced VRP: roadmap

The current version handles a simple TSP (single vehicle, no constraints). Time windows, vehicle capacities and multi-vehicle fleets are planned for a future version. Contact us if you need these capabilities.

Example — delivery tour

curl -X POST "https://api.tmaps.tn/routing/optimized?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "origin":      { "lat": 36.8355, "lng": 10.2261 },
  "waypoints": [
    { "lat": 36.8485, "lng": 10.1712 },
    { "lat": 36.8644, "lng": 10.1808 },
    { "lat": 36.8664, "lng": 10.1938 },
    { "lat": 36.8779, "lng": 10.2024 }
  ],
  "profile":     "driving",
  "optimize":    "duration",
  "roundtrip":   true
}'

Response

{
"distance": 14820,
"duration": 1680,
"order": [2, 0, 3, 1],
"geometry": "ahvqEi}_iL...",
"legs": [
  {
    "from":     { "lat": 36.8355, "lng": 10.2261 },
    "to":       { "lat": 36.8664, "lng": 10.1938 },
    "distance": 3120,
    "duration": 380
  },
  {
    "from":     { "lat": 36.8664, "lng": 10.1938 },
    "to":       { "lat": 36.8485, "lng": 10.1712 },
    "distance": 2940,
    "duration": 320
  }
]
}

Reading the response

order is a zero-indexed array describing the optimized order in which to visit the original waypoints. In this example: visit waypoints[2] first, then waypoints[0], then waypoints[3], then waypoints[1].
distance and duration are the totals for the full tour (origin → all waypoints in optimized order → optional destination or return).
legs details each segment in the optimized order.

Reorder client-side

To display the tour to a driver, project order onto your original list: const sorted = order.map(i => waypoints[i]).

Use cases

Express delivery: minimize distance for a courier with 10 parcels.
Inspection tours: optimal order of sites to visit by a field agent.
Maintenance: technician routes (network, equipment, etc.).

Limits

Max 50 waypoints per request. For larger fleets, batch and call the API multiple times.
No time windows or capacities in this version (see the callout above).

Errors

Status	Cause
`400`	Invalid body, more than 50 waypoints
`401`	Missing or revoked `api_key`
`403`	Domain not authorized
`404`	No route computable (at least one waypoint outside coverage)

See Error codes for the full list.