Tune Routing
Understand how the Matrix and Route API parameters control and customize your itinerary results.
The avoid parameter (Matrix, Route, and Isochrone)
The avoid parameter is an optional setting used when routing to influence the calculated path by instructing the algorithm to steer clear of certain road types or features.
It gives you control over the nature of the route, ensuring it meets specific user preferences or operational requirements.
How it works
When the avoid parameter is included in a routing request, the service attempts to find the most optimal route that does
not include the specified features.
The parameter accepts one or more values, typically separated by pipes (|), to define what the route should bypass.
| avoid Value | Description |
|---|---|
| tolls | Avoids roads that require the payment of a toll. |
| highways | Avoids major, high-speed roads classified as highways. |
| ferries | Avoids routes that require a ferry crossing. |
You can also bypass custom zones by defining them as a polygon. To do this, pass the coordinates of the polygon’s vertices in the following format:
- Each zone requires a minimum of three coordinates.
- Coordinates must be formatted as latitude,longitude.
- Individual coordinates must be separated by a semicolon (;).
You can combine multiple custom zones or mix custom zones with predefined features (like tolls or highways) by separating each value with a pipe character.
example : avoid=tolls|42.2345,2.4536;42.35664,2.66736;43.34534,3.25534|42.5543,2.2565;42.67764,2.5625;43.6736,3.5545
Note that sometimes ferries, highways, or tolls are required to complete a route, so setting those parameters is not guaranteed to avoid them entirely.
The total perimeter of each zone cannot exceed 10 km.
Traffic awareness parameters (Matrix, Route, Tolls)
To get route calculation taking into account live traffic conditions, historical traffic patterns, or time-dependent
restrictions, you can either use the departure_time or arrival_time parameters.
departure_time
Specifies the date/time at which the journey being calculated will take place to better calculate distances and times based on the predicted traffic for that date/time.
Valid values are timestamp or now.
e.g. 22/09/2020 20:26:13 ==> 1600799173
arrival_time
Specifies the date/time at which the user hopes to arrive at the destination. This data will then be used to better calculate distances and times based on the predicted traffic for that date/time.
Valid values are timestamp.
e.g. 22/09/2020 20:26:13 ==> 1600799173
Use either arrival_time or departure_time, not both.
To benefit from traffic data, you must enable the “Distance with traffic” addon.
Distance API with Traffic awareness is mostly based on the Here Routing API. More details on coverage information are available here.
The waypoint parameter (Route, Tolls)
Helps to find the optimized route between several locations.
To calculate a route that passes through multiple stops (such as when delivering several packages) use
the waypoints parameter.
– Example: waypoints=48.850077,3.311124|48.850077,3.411124 .
By default, the Route API finds the best path while maintaining the order of your specified locations.
To find the absolute most optimized route without respecting the input order, set the option optimize:true.
– Example: waypoints=optimize:true|48.850077,3.311124|48.850077,3.411124.
By default, Route API try to find the fastest route, if you want the shortest use the parameter method=distance
alternatives and waypoints can not be used at the same time.
The alternatives parameter (Route, Tolls)
Specifies if alternative routes should be returned. Valid values are true and false(default is false).
Depending on the calculated route, alternatives may not be provided.
The routes are sorted by time or duration depending on the method parameters (default is duration).
The recommended route will have the value recommended: true in the response.
alternatives and waypoints can not be used at the same time.
The details parameter (Route)
To retrieve all the data required for a complete roadbook, include the parameter details=full in your request.
The response will then contain a steps array within each route leg, providing detailed, step-by-step instructions and
maneuvers to reach the destination from the origin.
The roadbook instructions are generated in the requested language (if available). If the specified language is not
supported, the API will use English by default. Check Supported Languages
No steps are included in responses of traffic-aware requests.
Following the Roadbooks Steps
When a request is made with the details parameter set to full, the response will include a legs element containing
an array of steps. Each step contains the following fields:
distance: the distance covered by this stepduration: the estimated travel time for this stepstart_location: the starting location of this stepend_location: the ending location of this stepinstructions: textual instructions for this step, provided by the Distance API service (formatted according to the language parameter)polyline: the polyline encoding of the step
Each instructions contains the following fields:
action: the action to take for the current step (turn left, merge, straight, etc.). See below for a list.summary: Written maneuver instructionverbal_alert: text suitable to prepare the user for the coming transistionverbal_succint: text suitable for use as a verbal alert in a navigation applicationverbal_before: text suitable for use as a verbal message immediately prior to the maneuver transitionverbal_after: text suitable for use as a verbal message immediately after the maneuver transition
For action, the allowed values include:
| 0 | none |
| 1 | start |
| 2 | start right |
| 3 | start left |
| 4 | destination |
| 5 | destination right |
| 6 | destination left |
| 7 | becomes |
| 8 | continue |
| 9 | slight right |
| 10 | right |
| 11 | sharp right |
| 12 | uturn right |
| 13 | uturn left |
| 14 | sharp left |
| 15 | left |
| 16 | slight left |
| 17 | ramp straight |
| 18 | ramp right |
| 19 | ramp left |
| 20 | exit right |
| 21 | exit left |
| 22 | stay straight |
| 23 | stay right |
| 24 | stay left |
| 25 | merge |
| 26 | roundabout enter |
| 27 | roundabout exit |
| 28 | ferry enter |
| 29 | ferry exit |
| 30 | transit |
| 31 | transit transfer |
| 32 | transit remain on |
| 33 | transit connection start |
| 34 | transit connection transfer |
| 35 | transit connection destination |
| 36 | post transit connection destination |
| 37 | merge right |
| 38 | merge left |