Routing Mode Tutorial#
This tutorial provides clear usage examples for each routingMode supported by the routing API. Each example includes:
- ✅ A practical use case
- A ready-to-use JSON payload
- An explanation of what the request does
How to set the routing mode
To define the routing mode, simply include the routingMode field in your routing request JSON. Example:
"routingMode": "MODE_VIAS"MODE_VIAS: Standard route with waypoints#
Use case
Compute a standard route from point A to B to C, following the given order.
Example
{
"routingMode": "MODE_VIAS",
"destinations": [
{ "coordinateSat": { "lon": 4.81594, "lat": 45.75508 } },
{ "coordinateSat": { "lon": 5.04476, "lat": 47.33372 } },
{ "coordinateSat": { "lon": 2.34241, "lat": 48.85223 } }
],
"options": ["POLYLINE"],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}What it does
Calculates a single route from Lyon → Dijon → Paris, in the exact order.
Response
{
"usedDestinations": [
{
"inputOrder": 0,
"used": true,
"usedOrder": 0,
"matchedCoordinateGps": {
"lon": 4.815940190524969,
"lat": 45.75508125
},
"confidenceValue": 0.3742419867167196,
"distanceFromRequest": 0.14,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 1,
"used": true,
"usedOrder": 1,
"matchedCoordinateGps": {
"lon": 5.044754103431373,
"lat": 47.33364875
},
"confidenceValue": 0.3017814726840855,
"distanceFromRequest": 7.94,
"polylineIndex": -1,
"duration": 7202,
"length": 195778
},
{
"inputOrder": 2,
"used": true,
"usedOrder": 2,
"matchedCoordinateGps": {
"lon": 2.3423590873895535,
"lat": 48.85218
},
"confidenceValue": 0.16602793114647615,
"distanceFromRequest": 6.7,
"polylineIndex": -1,
"duration": 18933,
"length": 510058
}
],
"routingRoutes": [
{
"length": 510058,
"duration": 18933,
"trafficDelay": 0,
"averageSpeed": 96.984566,
"maximumSpeed": 0,
"startUTurnThreshold": 3000,
"boundingBox": {
"minLon": 2.30612,
"minLat": 45.7515,
"maxLon": 5.08011,
"maxLat": 48.85218
},
"startStopInfo": {
"start": {
"lon": 4.81594,
"lat": 45.75508
},
"stop": {
"lon": 2.34236,
"lat": 48.85218
},
"distanceFirstMatched": 0.14,
"distanceLastMatched": 0,
"interDests": null
},
"polyline": [
{
"lon": 4.815940190524969,
"lat": 45.75508125
},
{
"lon": 4.81627,
"lat": 45.75484
},MODE_1_TO_N: One origin to many destinations#
Use case
Compute separate routes from a single starting point to multiple destinations.
Example
{
"routingMode": "MODE_1_TO_N",
"destinations": [
{ "coordinateSat": { "lon": 4.8357, "lat": 45.7640 } },
{ "coordinateSat": { "lon": 5.3698, "lat": 43.2965 } },
{ "coordinateSat": { "lon": 7.2619, "lat": 43.7102 } },
{ "coordinateSat": { "lon": 2.3522, "lat": 48.8566 } }
],
"options": ["POLYLINE"],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}What it does
Returns individual routes from Lyon to each destination:
Response
- Lyon → Marseille
- Lyon → Nice
- Lyon → Paris
{
"usedDestinations": [
{
"inputOrder": 0,
"used": true,
"usedOrder": 0,
"matchedCoordinateGps": {
"lon": 4.83554,
"lat": 45.76412
},
"confidenceValue": 0.33438985736925514,
"distanceFromRequest": 18.24,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 1,
"used": true,
"usedOrder": 1,
"matchedCoordinateGps": {
"lon": 5.37028,
"lat": 43.29654
},
"confidenceValue": 0.4295641187618445,
"distanceFromRequest": 39.14,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 2,
"used": true,
"usedOrder": 2,
"matchedCoordinateGps": {
"lon": 7.2619026033410385,
"lat": 43.7101925
},
"confidenceValue": 0.188395259216171,
"distanceFromRequest": 0.83,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 3,
"used": true,
"usedOrder": 3,
"matchedCoordinateGps": {
"lon": 2.3525263882048697,
"lat": 48.85722125
},
"confidenceValue": 0.007055115402485117,
"distanceFromRequest": 73.17,
"polylineIndex": -1,
"duration": -1,
"length": -1
}
],
"routingRoutes": [
{
"length": 314264,
"duration": 11317,
"trafficDelay": 0,
"averageSpeed": 99.96911,
"maximumSpeed": 0,
"startUTurnThreshold": 3000,
"boundingBox": {
"minLon": 4.70685,
"minLat": 43.29515,
"maxLon": 5.37173,
"maxLat": 45.76617
},
"startStopInfo": {
"start": {
"lon": 4.83554,
"lat": 45.76412
},
"stop": {
"lon": 5.37028,
"lat": 43.29654
},
"distanceFirstMatched": 0,
"distanceLastMatched": 0,
"interDests": null
},
"polyline": [
{
"lon": 4.83554,
"lat": 45.76412
},
{
"lon": 4.83422,
"lat": 45.76421
},MODE_N_TO_1: Many origins to one destination#
Use case
Calculate independent routes from multiple origins to a single destination.
Example
{
"routingMode": "MODE_N_TO_1",
"destinations": [
{ "coordinateSat": { "lon": 4.8357, "lat": 45.7640 } },
{ "coordinateSat": { "lon": 6.1294, "lat": 46.2044 } },
{ "coordinateSat": { "lon": 5.7224, "lat": 45.1885 } },
{ "coordinateSat": { "lon": 5.0415, "lat": 47.3220 } }
],
"options": ["POLYLINE"],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}What it does
Returns routes from Lyon, Geneva, and Grenoble to Dijon (last point is the destination).
Response
{
"usedDestinations": [
{
"inputOrder": 0,
"used": true,
"usedOrder": 0,
"matchedCoordinateGps": {
"lon": 4.83554,
"lat": 45.76412
},
"confidenceValue": 0.33438985736925514,
"distanceFromRequest": 18.24,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 1,
"used": true,
"usedOrder": 1,
"matchedCoordinateGps": {
"lon": 6.12971,
"lat": 46.20452
},
"confidenceValue": 0.8268272425249169,
"distanceFromRequest": 27.37,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 2,
"used": true,
"usedOrder": 2,
"matchedCoordinateGps": {
"lon": 5.722293645827602,
"lat": 45.18855125
},
"confidenceValue": 0.7293058379320361,
"distanceFromRequest": 10.11,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 3,
"used": true,
"usedOrder": 3,
"matchedCoordinateGps": {
"lon": 5.0419,
"lat": 47.32316
},
"confidenceValue": 0.011090957769868685,
"distanceFromRequest": 132.61,
"polylineIndex": -1,
"duration": -1,
"length": -1
}
],
"routingRoutes": [
{
"length": 196040,
"duration": 7554,
"trafficDelay": 0,
"averageSpeed": 93.42653,
"maximumSpeed": 0,
"startUTurnThreshold": 3000,
"boundingBox": {
"minLon": 4.71619,
"minLat": 45.75105,
"maxLon": 5.08011,
"maxLat": 47.32631
},
"startStopInfo": {
"start": {
"lon": 4.83554,
"lat": 45.76412
},
"stop": {
"lon": 5.0419,
"lat": 47.32316
},
"distanceFirstMatched": 0,
"distanceLastMatched": 0,
"interDests": null
},
"polyline": [
{
"lon": 4.83554,
"lat": 45.76412
},
{
"lon": 4.83422,
"lat": 45.76421
},MODE_N_TO_N: Routes between every pair of N points#
Use case
Compute all possible routes between each pair of N locations.
Example
{
"routingMode": "MODE_N_TO_N",
"destinations": [
{ "coordinateSat": { "lon": 4.83554, "lat": 45.76412 } },
{ "coordinateSat": { "lon": 5.37028, "lat": 43.29654 } },
{ "coordinateSat": { "lon": 1.48529, "lat": 43.63876 } },
{ "coordinateSat": { "lon": 2.34212, "lat": 48.82982 } }
],
"options": ["POLYLINE"],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}What it does
Returns 12 route combinations (4x3): every origin/destination pair, except a point with itself, n points give n²−n routes (the specification's description of MODE_N_TO_N says n²). For a value between every pair, the point with itself included (n²), see MODE_MATRIX.
Response
{
"usedDestinations": [
{
"inputOrder": 0,
"used": true,
"usedOrder": 0,
"matchedCoordinateGps": {
"lon": 4.83554,
"lat": 45.76412
},
"confidenceValue": 0.3741339491916859,
"distanceFromRequest": 0,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 1,
"used": true,
"usedOrder": 1,
"matchedCoordinateGps": {
"lon": 5.37028,
"lat": 43.29654
},
"confidenceValue": 0.20007719027402546,
"distanceFromRequest": 0,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 2,
"used": true,
"usedOrder": 2,
"matchedCoordinateGps": {
"lon": 1.4852923354376975,
"lat": 43.638755
},
"confidenceValue": 0.2616331886544867,
"distanceFromRequest": 0.56,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 3,
"used": true,
"usedOrder": 3,
"matchedCoordinateGps": {
"lon": 2.34205,
"lat": 48.83009
},
"confidenceValue": 1,
"distanceFromRequest": 30.49,
"polylineIndex": -1,
"duration": -1,
"length": -1
}
],
"routingRoutes": [
{
"length": 314264,
"duration": 11317,
"trafficDelay": 0,
"averageSpeed": 99.96911,
"maximumSpeed": 0,
"startUTurnThreshold": 3000,
"boundingBox": {
"minLon": 4.70685,
"minLat": 43.29515,
"maxLon": 5.37173,
"maxLat": 45.76617
},
"startStopInfo": {
"start": {
"lon": 4.83554,
"lat": 45.76412
},
"stop": {
"lon": 5.37028,
"lat": 43.29654
},
"distanceFirstMatched": 0,
"distanceLastMatched": 0,
"interDests": null
},
"polyline": [
{
"lon": 4.83554,
"lat": 45.76412
},
{
"lon": 4.83422,
"lat": 45.76421
},MODE_MATRIX: Distance / time / energy matrix#
Use case
Get a matrix of distances, travel times or energy consumption between multiple origins and destinations.
Example
{
"routingMode": "MODE_MATRIX",
"destinations": [
{ "coordinateSat": { "lon": 4.83554, "lat": 45.76412 } },
{ "coordinateSat": { "lon": 5.6943, "lat": 45.18019 } },
{ "coordinateSat": { "lon": 5.40638, "lat": 43.32238 } },
{ "coordinateSat": { "lon": 1.45128, "lat": 43.61487 } }
],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}What it does
Returns a table (matrix) with one value per pair of points: the weight of the criterion set in routingCriterias, seconds in duration under FASTEST (the default), metres in length under SHORTEST, Wh in energyConsumption under ECO_ENERGY, per the specification. The other two fields are -1. With 4 points, the answer holds 16 entries, row by row: entry i × 4 + j goes from point i to point j (0 from a point to itself). No route geometry is included, so the POLYLINE option is not needed. Read duration, not totalDuration, which is 0 in every matrix entry.
Note: measured on production (29 September 2026), under ECO_ENERGY each energyConsumption is the pair's FASTEST duration divided by 1 000 (4 558 s gives 4.558), whatever the energy features sent.
Response
{
"usedDestinations": [
{
"inputOrder": 0,
"used": true,
"usedOrder": 0,
"matchedCoordinateGps": {
"lon": 4.83554,
"lat": 45.76412
},
"confidenceValue": 0.3741339491916859,
"distanceFromRequest": 0,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 1,
"used": true,
"usedOrder": 1,
"matchedCoordinateGps": {
"lon": 5.694295961447033,
"lat": 45.18018875
},
"confidenceValue": 0.06747539959389807,
"distanceFromRequest": 0.14,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 2,
"used": true,
"usedOrder": 2,
"matchedCoordinateGps": {
"lon": 5.4063817189367205,
"lat": 43.32238125
},
"confidenceValue": 0.16168673195683364,
"distanceFromRequest": 0.14,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 3,
"used": true,
"usedOrder": 3,
"matchedCoordinateGps": {
"lon": 1.4512833045462004,
"lat": 43.6148675
},
"confidenceValue": 0.1723633461896529,
"distanceFromRequest": 0.28,
"polylineIndex": -1,
"duration": -1,
"length": -1
}
],
"routingRoutes": [
{
"length": -1,
"duration": 0,
"trafficDelay": 0,
"averageSpeed": 0,
"maximumSpeed": 0,
"startUTurnThreshold": 0,
"energyConsumption": -1
},
{
"length": -1,
"duration": 4723,
"trafficDelay": 0,
"averageSpeed": 0,
"maximumSpeed": 0,
"startUTurnThreshold": 0,
"energyConsumption": -1
},MODE_ISOCHRONE: Reachable area#
Use case
Visualize the area reachable within a given time, distance, or energy limit.
Example: From one point (Lyon)
{
"routingMode": "MODE_ISOCHRONE",
"destinations": [
{ "coordinateSat": { "lon": 4.8357, "lat": 45.7640 } }
],
"isoChroneLimit": 1800,
"options": ["POLYLINE"],
"routingVehicleProfile": {
"transportMode": "CAR"
}
}What it does
Returns the polygon representing the zone reachable within 30 minutes from Lyon.
Response
{
"usedDestinations": [
{
"inputOrder": 0,
"used": true,
"usedOrder": 0,
"matchedCoordinateGps": {
"lon": 4.83554,
"lat": 45.76412
},
"confidenceValue": 0.33438985736925514,
"distanceFromRequest": 18.24,
"polylineIndex": -1,
"duration": -1,
"length": -1
}
],
"routingRoutes": [
{
"length": 0,
"duration": 0,
"trafficDelay": 0,
"averageSpeed": 0,
"maximumSpeed": 0,
"startUTurnThreshold": 0,
"boundingBox": {
"minLon": 4.56677,
"minLat": 45.5055,
"maxLon": 5.19823,
"maxLat": 46.00572
},
"polyline": [
{
"lon": 4.96174,
"lat": 45.87819
},
{
"lon": 4.96793,
"lat": 45.88438
},Example: From two points with energy constraint
{
"routingMode": "MODE_ISOCHRONE",
"destinations": [
{ "coordinateSat": { "lon": 4.8357, "lat": 45.7640 } },
{ "coordinateSat": { "lon": 4.9000, "lat": 45.5600 } }
],
"isoChroneLimit": 3000,
"routingCriterias": ["ECO_ENERGY"],
"options": ["POLYLINE"],
"routingVehicleProfile": {
"transportMode": "CAR",
"routingEnergyVehicleFeature": {
"batCapacity": 60,
"energyLoad": 50,
"engineEfficiency": 0.92,
"scx": 0.7,
"crr": 0.013,
"payload": 100,
"dryWeight": 1600,
"auxConsumption": 500,
"extTemp": 20,
"maxAccel": 1.5,
"maxDecel": -1.5
}
}
}What it does
Returns the area reachable from Lyon to Serpaize (Isère) using 3000 Wh of energy. Useful for EV range visualization.
isoChroneLimit is in the unit of the criterion, per the specification: Wh under ECO_ENERGY, seconds under FASTEST (the default), metres under SHORTEST. ECO_ENERGY requires routingVehicleProfile.routingEnergyVehicleFeature: without it, the service answers 400 {"code":"VehicleProfileIsRequiredException","message":"Vehicle profile (vp) is required! Or add energy vehicle profile (evf) !"}, even when a routingVehicleProfile is sent (evf there is routingEnergyVehicleFeature).
Note: measured on production (29 September 2026), this polygon is identical to the FASTEST isochrone with isoChroneLimit: 3000 (seconds), and does not change with the energy features sent.
Response
{
"usedDestinations": [
{
"inputOrder": 0,
"used": true,
"usedOrder": 0,
"matchedCoordinateGps": {
"lon": 4.83554,
"lat": 45.76412
},
"confidenceValue": 0.33438985736925514,
"distanceFromRequest": 18.24,
"polylineIndex": -1,
"duration": -1,
"length": -1
},
{
"inputOrder": 1,
"used": true,
"usedOrder": 1,
"matchedCoordinateGps": {
"lon": 4.89971,
"lat": 45.55845
},
"confidenceValue": 0.2467450352129857,
"distanceFromRequest": 174.02,
"polylineIndex": -1,
"duration": -1,
"length": -1
}
],
"routingRoutes": [
{
"length": 0,
"duration": 0,
"trafficDelay": 0,
"averageSpeed": 0,
"maximumSpeed": 0,
"startUTurnThreshold": 0,
"boundingBox": {
"minLon": 4.73271,
"minLat": 45.50303,
"maxLon": 4.92389,
"maxLat": 45.78482
},
"polyline": [
{
"lon": 4.81835,
"lat": 45.63508
},
{
"lon": 4.82443,
"lat": 45.64226
},