Itinéraire — Direction

Calculez un itinéraire optimal entre deux points ou plus, avec turn-by-turn, distance, durée et géométrie.

L’endpoint Direction calcule l’itinéraire optimal entre un point de départ et un ou plusieurs points d’arrivée (waypoints). Il renvoie la distance totale, la durée estimée, la géométrie et — sur demande — les instructions turn-by-turn.

Endpoint

Deux variantes équivalentes :

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

Utilisez GET pour les itinéraires simples (2 points). Utilisez POST dès que vous avez plusieurs waypoints ou des options avancées.

Paramètres

Paramètres communs (query GET ou body POST)

Param	Type	Requis	Défaut	Description
`api_key`	string	oui	—	Votre clé API TMaps (toujours en query string, même en POST).
`from`	string	—	—	[GET] Point de départ `lat,lng`.
`to`	string	—	—	[GET] Point d'arrivée `lat,lng`.
`waypoints`	array	—	—	[POST] Liste ordonnée de points `{ lat, lng }` (min 2, max 25).
`profile`	string	—	`driving`	Profil de transport : `driving`, `walking`, `cycling`, `truck`.
`geometry`	string	—	`polyline`	Format de la géométrie de retour : `polyline` (Google polyline encodé) ou `geojson`.
`steps`	boolean	—	`false`	Si `true`, renvoie les instructions turn-by-turn.
`alternatives`	boolean	—	`false`	Si `true`, renvoie jusqu'à 2 itinéraires alternatifs.
`avoid`	string	—	—	Liste séparée par virgule des éléments à éviter : `tolls`, `highways`, `ferries`.
`language`	string	—	`fr`	Langue des instructions : `fr`, `en`, `ar`.

Exemple — 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"

Exemple — 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"
}'

Réponse

{
"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": "Continuez sur Avenue Habib Bourguiba", "distance": 320, "duration": 50 },
      { "instruction": "Tournez à droite sur 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": "Prenez l'autoroute A1 direction Carthage", "distance": 12300, "duration": 850 }
    ]
  }
]
}

Champs renvoyés

Champs racine

Param	Type	Requis	Défaut	Description
`distance`	number	—	—	Distance totale en mètres.
`duration`	number	—	—	Durée estimée totale en secondes.
`geometry`	string\|object	—	—	Polyline encodée (par défaut) ou objet GeoJSON LineString si `geometry=geojson`.
`legs`	array	—	—	Sous-itinéraires entre chaque paire de waypoints consécutifs.
`alternatives`	array	—	—	Présent uniquement si `alternatives=true` : liste d'itinéraires alternatifs (mêmes champs que la racine).

Décoder la polyline

Si vous gardez geometry=polyline (par défaut), utilisez la lib polyline pour la décoder côté client. Sinon passez geometry=geojson et tracez directement la LineString.

Profils de transport

Profil	Description
`driving`	Voiture (par défaut). Tient compte du sens de circulation et des restrictions urbaines.
`walking`	Piéton. Inclut allées, escaliers et zones piétonnes.
`cycling`	Vélo. Privilégie les voies cyclables quand elles existent.
`truck`	Poids lourd. Évite les routes interdites aux camions et tient compte des limitations de tonnage.

Cas d’usage

Apps de livraison : itinéraire restaurant → client avec ETA.
Tourisme : enchaînement de sites avec durée totale.
Mobilité douce : profils walking et cycling pour des apps urbaines.
B2B logistique : profil truck pour les flottes de poids lourds.

Erreurs

Statut	Cause
`400`	Coordonnées manquantes ou hors plage, profil inconnu
`401`	`api_key` manquant ou révoqué
`403`	Domaine non autorisé
`404`	Aucun itinéraire trouvé entre les points (zone non couverte)

Voir Codes d’erreur pour la liste complète.