Common Parameters
This guide describes common parameters and features shared by the Routing API and Isochrones API.
Both APIs reject request fields they do not know with HTTP 400 (invalid request). For example, the Isochrones API does not accept the electric vehicle fields of vehicle.
Transport Modes
Both APIs accept a transport parameter to specify the mode of transportation:
| Value | Description | Routing | Isochrones |
|---|---|---|---|
car | Standard car routing | ✅ | ✅ |
lorry | Lorry / heavy goods | ✅ | ✅ |
truck | Alias for lorry | ✅ | ✅ |
bike | Bicycle routing | ✅ | ✅ |
pedestrian | Walking / hiking | ✅ | ✅ |
public | Public transit | ✅ | — |
Route Types
The type parameter controls the optimization goal:
| Value | Description | Routing | Isochrones |
|---|---|---|---|
fastest | Minimize travel time | ✅ | ✅ (ranges in seconds) |
shortest | Minimize distance | ✅ | ✅ (ranges in meters) |
economic | Optimize energy consumption (e-bikes only) | ✅ | ✅ (ranges in Wh) |
scenic | Prioritize scenic roads (car/truck only) | ✅ | ✅ |
The accepted route types depend on the transport mode; any other combination is rejected as an invalid request:
| Transport mode | Accepted route types |
|---|---|
car, lorry, truck | fastest, shortest, scenic |
bike | fastest, shortest; economic only with an e-bike profile (*_pedelec, *_spedelec) |
pedestrian | fastest, shortest |
public | fastest |
Route Avoidance
The avoid array lets you exclude specific road features from the computed route or isochrone:
| Value | Description | Routing | Isochrones |
|---|---|---|---|
highway | Avoid highways / motorways | ✅ | ✅ |
toll | Avoid toll roads | ✅ | ✅ |
ferry | Avoid ferry connections | ✅ | ✅ |
unpaved | Avoid unpaved roads | ✅ | ✅ |
turnaround | Avoid U-turns at intermediate waypoints. Default is true for car/truck (false when emergency is true) and public, false for bike/pedestrian | ✅ | ✅ |
traffic | Avoid current traffic congestions and roadblocks. If no route is possible, a solution with best-effort roadblock avoidance is returned | ✅ | ✅ |
roadblocks | Avoid only roadblocks. If no route is possible, a best-effort solution is returned | ✅ | ✅ |
immutable_roadblocks | Avoid permanent roadblocks. If no route is possible, a "waypoints access" error is returned instead of a fallback | ✅ | ✅ |
Vehicle Specifications
The vehicle object allows detailed configuration of vehicle characteristics. It is supported by both APIs.
Transport Profiles
The profile field selects a detailed profile within a transport mode:
Bike profiles:
| Profile | Description | Routing | Isochrones |
|---|---|---|---|
road | Road bike | ✅ | ✅ |
cross | Cross / gravel bike | ✅ | ✅ |
city | City / urban bike (default) | ✅ | ✅ |
mountain | Mountain bike | ✅ | ✅ |
E-bike pedelec profiles:
| Profile | Description | Routing | Isochrones |
|---|---|---|---|
road_pedelec | Road e-bike (pedelec) | ✅ | ✅ |
cross_pedelec | Cross e-bike (pedelec) | ✅ | ✅ |
city_pedelec | City e-bike (pedelec) | ✅ | ✅ |
mountain_pedelec | Mountain e-bike (pedelec) | ✅ | ✅ |
E-bike speed pedelec profiles:
| Profile | Description | Routing | Isochrones |
|---|---|---|---|
road_spedelec | Road e-bike (speed pedelec) | ✅ | ✅ |
cross_spedelec | Cross e-bike (speed pedelec) | ✅ | ✅ |
city_spedelec | City e-bike (speed pedelec) | ✅ | ✅ |
mountain_spedelec | Mountain e-bike (speed pedelec) | ✅ | ✅ |
Pedestrian profiles:
| Profile | Description | Routing | Isochrones |
|---|---|---|---|
walk | Standard walking (default) | ✅ | ✅ |
hike | Hiking | ✅ | ✅ |
Physical Properties
| Parameter | Type | Description |
|---|---|---|
mass | integer | Vehicle mass in kg; for bike transport, the mass of the e-bike |
height | integer | Vehicle height in cm |
length | integer | Vehicle length in cm |
width | integer | Vehicle width in cm |
axle | integer | Axle load in kg |
speed | float | Reference speed in m/s, greater than 0 when given. For car and truck transport it is the vehicle max speed; for bike transport the e-bike reference speed, used only with an e-bike profile; not used for pedestrian |
These properties are used to compute routes that respect dimensional and weight restrictions on roads (e.g., low bridges, weight-limited roads). Negative values are rejected as an invalid request.
Fuel and Electric Vehicle Properties
| Parameter | Type | Description | Routing | Isochrones |
|---|---|---|---|---|
fuel | string | Fuel type: electric, petrol, diesel, lpg. For electric with car/truck, EV routing is used with intermediate charging station stops; it requires charger_ports (at least one valid port) and range > 0, otherwise the request is rejected | ✅ | — |
batt_capacity | integer | Battery capacity in Wh (for EV and e-bikes) | ✅ | — |
charger_ports | string[] | Available charging port types (see below) | ✅ | — |
range | integer | Vehicle range in meters (currently EV only) | ✅ | — |
charge | integer | Kilometers charged in one hour (with battery between 10%–80%) | ✅ | — |
departure_soc | float | Departure battery state of charge (0 = empty, 1 = full) | ✅ | — |
destination_soc | float | Minimum SoC when arriving at destination | ✅ | — |
chargerArrival_soc | float | Minimum SoC when arriving at a charging station | ✅ | — |
chargerDeparture_soc | float | Maximum SoC when leaving a charging station | ✅ | — |
charger_overhead | float | Overhead time at a charging station in minutes | ✅ | — |
plate | string | Vehicle plate, used for road access restrictions based on plate mantissa | ✅ | — |
Supported charger_ports values:
| Value | Description |
|---|---|
type1 | Type 1 (SAE J1772) AC connector |
type2 | Type 2 (IEC 62196) AC connector |
nacs | North American Charging Standard (Tesla) |
ccs1 | Combined Charging System 1 |
ccs2 | Combined Charging System 2 |
chademo | CHAdeMO DC connector |
chaoji | ChaoJi high-power DC connector |
gbt_ac | GB/T AC connector (China standard) |
gbt_dc | GB/T DC connector (China standard) |
Geometry Encoding
The geometry parameter controls how path coordinates are encoded in the response:
| Value | Format |
|---|---|
lineString | Coordinate array [[lon, lat, alt], ...] (default for Routing); isochrone polygons carry no alt |
polyline | Google encoded polyline string |
Fitness Factor
The fitness parameter (float, 0–1) tunes bike and pedestrian routing to the user's fitness level. Lower values favor flatter, easier routes; higher values allow steeper, more direct paths. Values outside 0–1 are rejected as an invalid request. Default: 0.5.
Emergency Mode
Setting emergency to true enables emergency vehicle routing, which grants access to roads flagged as "emergency only" and ignores left/right turn restrictions.
Geofence Avoidance
Both APIs support geofence-based route avoidance:
| Parameter | Description |
|---|---|
avoid_geofence_areas | Array of geofence area tags/names to avoid |
avoid_geofence_anti_areas | Array of geofence anti-area tags/names to avoid |
For more details on creating and managing geofences, see Geofences & Asset Monitoring.
Locale
The locale parameter sets the language of the Routing API navigation instructions. It accepts a lowercase ISO 639-1 code (e.g., en, de, fr) or an ISO 639-2 code (e.g., eng), optionally with a region (e.g., en-US). A code that cannot be parsed is rejected as an invalid request; a language without translations falls back to the closest available one. The Isochrones API accepts the same codes, but its result contains no translated text. Default: en.
Debug
Setting debug to true formats the JSON response with indentation for easier human readability. Default: false.
Related Documentation
For detailed usage and examples of route computation, see Routing API.
For calculating reachable areas from a given location, see Isochrones API.