Directions

Compute the optimal route between two or more points, with turn-by-turn, distance, duration and geometry.

The Direction endpoint computes the optimal route between a starting point and one or more destination points (waypoints). It returns the total distance, the estimated duration, the geometry and — on demand — turn-by-turn instructions.

Endpoint

Two equivalent variants:

GET https://api.tmaps.tn/routing/direction?from=lat,lng&to=lat,lng&api_key=YOUR_API_KEY

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

Use GET for simple two-point routes. Use POST as soon as you have multiple waypoints or advanced options.

Parameters

Common parameters (GET query or POST body)

Param	Type	Requis	Défaut	Description
`api_key`	string	oui	—	Your TMaps API key (always in the query string, even for POST).
`from`	string	—	—	[GET] Origin `lat,lng`.
`to`	string	—	—	[GET] Destination `lat,lng`.
`waypoints`	array	—	—	[POST] Ordered list of points `{ lat, lng }` (min 2, max 25).
`profile`	string	—	`driving`	Transport profile: `driving`, `walking`, `cycling`, `truck`.
`geometry`	string	—	`polyline`	Geometry format: `polyline` (Google encoded polyline) or `geojson`.
`steps`	boolean	—	`false`	If `true`, returns turn-by-turn instructions.
`alternatives`	boolean	—	`false`	If `true`, returns up to 2 alternative routes.
`avoid`	string	—	—	Comma-separated list of items to avoid: `tolls`, `highways`, `ferries`.
`language`	string	—	`fr`	Language for instructions: `fr`, `en`, `ar`.

Example — GET (simple)

curl "https://api.tmaps.tn/routing/direction?from=36.8002,10.1815&to=36.8528,10.3261&profile=driving&api_key=YOUR_API_KEY"

Example — POST (multi-waypoints + steps)

curl -X POST "https://api.tmaps.tn/routing/direction?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "waypoints": [
    { "lat": 36.7992, "lng": 10.1709 },
    { "lat": 36.8094, "lng": 10.1400 },
    { "lat": 36.8528, "lng": 10.3261 }
  ],
  "profile": "driving",
  "steps": true,
  "geometry": "geojson"
}'

Response

{
"distance": 19420,
"duration": 1830,
"geometry": {
  "type": "LineString",
  "coordinates": [
    [10.1709, 36.7992],
    [10.1655, 36.8021],
    [10.1400, 36.8094],
    [10.2630, 36.8420],
    [10.3261, 36.8528]
  ]
},
"legs": [
  {
    "distance": 4870,
    "duration": 540,
    "from": { "lat": 36.7992, "lng": 10.1709 },
    "to":   { "lat": 36.8094, "lng": 10.1400 },
    "steps": [
      { "instruction": "Continue on Avenue Habib Bourguiba", "distance": 320, "duration": 50 },
      { "instruction": "Turn right onto Rue de Carthage",    "distance": 180, "duration": 30 }
    ]
  },
  {
    "distance": 14550,
    "duration": 1290,
    "from": { "lat": 36.8094, "lng": 10.1400 },
    "to":   { "lat": 36.8528, "lng": 10.3261 },
    "steps": [
      { "instruction": "Take A1 motorway towards Carthage", "distance": 12300, "duration": 850 }
    ]
  }
]
}

Returned fields

Top-level fields

Param	Type	Requis	Défaut	Description
`distance`	number	—	—	Total distance in meters.
`duration`	number	—	—	Total estimated duration in seconds.
`geometry`	string\|object	—	—	Encoded polyline (default) or GeoJSON LineString object if `geometry=geojson`.
`legs`	array	—	—	Sub-routes between each consecutive waypoint pair.
`alternatives`	array	—	—	Present only if `alternatives=true`: list of alternative routes (same fields as the root).

Decode the polyline

If you keep geometry=polyline (default), use the polyline library to decode it on the client. Otherwise pass geometry=geojson and render the LineString directly.

Transport profiles

Profile	Description
`driving`	Car (default). Honors traffic direction and urban restrictions.
`walking`	Pedestrian. Includes alleys, stairs and pedestrian zones.
`cycling`	Bicycle. Prefers cycling lanes when available.
`truck`	Heavy goods vehicle. Avoids truck-restricted roads and respects weight limits.

Use cases

Delivery apps: restaurant → customer routing with ETA.
Tourism: chain of sites with total duration.
Soft mobility: walking and cycling profiles for urban apps.
B2B logistics: truck profile for heavy fleets.

Errors

Status	Cause
`400`	Missing or out-of-range coordinates, unknown profile
`401`	Missing or revoked `api_key`
`403`	Domain not authorized
`404`	No route found between points (uncovered area)

See Error codes for the full list.