Purpose
This document provides fundamental route planning parameters and types that can be used, among others, in the:
Please be aware that this document does not specify the complete request or response format. To maintain forward compatibility you must be able to process responses with additional non-documented data fields. Our deprecation policy only covers the documented subset of these formats.
Types
Types subset | Description |
---|
location
string
| Latitude, longitude pair (in EPSG:4326 projection), with the following constraints: Latitude values must be in the range [-90, +90] . Longitude values must be in the range [-180, +180] .
Example: 52.37245,4.89406 |
---|
point
object
| A location represented as a JSON object. The object should contain the two fields latitude and
longitude each containing a number, and expressed in the
same reference frame and with the same constraints as for the
location type.
Example:
{"latitude": 52.37245, "longitude": 4.89406} |
---|
dateTime
string
| A date and time specified in RFC 3339 format with an optional time zone offset.
Examples: 2023-12-19T16:39:57 2023-12-19T16:39:57-08:00
|
---|
CombustionConstantSpeedConsumptionPair
string (contains a pair of two, comma-separated floats)
| Comma-separated speedInkmh,consumptionInLitersPerHundredkm
pair with the following constraint: The speedInkmh values
must be in the range [0.0, 255.0] .
Example: 15.5,10.0 |
---|
ElectricConstantSpeedConsumptionPair
string (contains a pair of two, comma-separated floats)
| Comma-separated speedInkmh,consumptionInkWhPerHundredkm
pairs with the following constraint: The speedInkmh values
must be in the range [0.0, 255.0] .
Example: 15.5,8.0 |
---|
Request data
The following data table describes HTTP request headers of particular interest to the Calculate Route and Calculate Reachable Range service clients.
- Required headers must be used or the call will fail.
- Optional headers may be used.
- The order of request headers is not important.
Optional headers | Description |
---|
Accept-Encoding | Requests that the response be compressed.
Value: gzip |
---|
Content-Encoding | Specifies the used compression of the request body. Currently, only
gzip is supported. If not specified, no compression is
assumed. This is equal to specifying identity . Note: This header is optional and can only be used for
POST requests. Values: |
---|
Content-Type | Specifies the MIME type of the body of the request. Note: This header is required for POST requests. Value: application/json |
---|
Tracking-ID | Specifies an identifier for the request. - The value should be unique for each request.
The value must match the regular expression
'^[a-zA-Z0-9-_\.]{1,100}$' . If specified, the same value is sent back in the similar-named
response header. Otherwise, a generated value may be sent back.
|
---|
Base path parameters
Parameter subset
The following data table describes a subset of the parameters that can be used in the Calculate Route and Calculate Reachable Range services.
- Required parameters must be used or the call will fail.
- Optional parameters may be used.
Required parameters | Description |
---|
baseURL
string
| Base URL for calling the API.
Values: |
---|
Optional parameters | Description |
---|
contentType
string
| The content type of the response structure.
Possible values: Note: If the content type is jsonp , a callback method
can be specified in the query parameters. |
---|
Request parameters
Request parameters are presented in two sections:
Section 1. Common Routing Parameters
This section presents a set of loosely connected parameters that influence the operation of the routing algorithm. While some of them are associated, the majority can be used independently of the others.
- Required parameters must be used or the call will fail.
- Optional parameters may be used.
Required parameters | Description |
---|
key
string
| Authorization key to access the API.
Value: Your valid API Key . |
---|
Optional parameters | Description |
---|
callback
string
| Specifies the jsonp callback method. Only used when
contentType is jsonp .
Default value: callback |
---|
report
string
| Specifies which data should be reported for diagnostic purposes. A
possible value is: effectiveSettings . Reports the effective parameters or data used when calling the API. In the case of defaulted parameters, the default will be reflected
where the parameter was not specified by the caller.
Default value: effectiveSettings |
---|
departAt
string
| The date and time of departure from the origin point. Departure times apart from now must be specified as a
dateTime . When a time zone offset is not specified, it will be assumed to be
that of the origin point. The departAt parameter cannot be used in conjunction
with arriveAt .
Default value: now
Other value: dateTime |
---|
arriveAt
string
| The date and time of arrival at the destination point. The arriveAt parameter cannot be used in conjunction with: departAt minDeviationDistance minDeviationTime
It cannot be used in calculateReachableRange requests.
Value: dateTime |
---|
routeType
string
| Specifies the type of optimization used when calculating routes.
Possible values are: fastest : Route calculation is optimized by travel time,
while keeping the routes sensible. For example, the calculation may
avoid shortcuts along inconvenient side roads or long detours that
only save very little time.
shortest : Route calculation is optimized by travel
distance, while keeping the routes sensible. For example, straight
routes are preferred over those incurring turns.
short : Route calculation is optimized such that a good
compromise between small travel time and short travel distance is
achieved.
eco : Route calculation is optimized such that a good
compromise between small travel time and low fuel or energy
consumption is achieved.
thrilling : Route calculation is optimized such that
routes include interesting or challenging roads and use as few
motorways as possible.
You can choose the level of turns included and also the degree
of hilliness. See the hilliness and windingness
parameters to set this. There is a limit of 900km on routes planned with
routeType=thrilling .
Default value: fastest |
---|
traffic
boolean
| Possible values are: true : Do consider all available traffic information
during routing.
false : Ignore current traffic data during routing. Note
that although the current traffic data is ignored during routing,
the effect of historic traffic on effective road speeds is still
incorporated.
Depending on availability, the Routing API takes road closures and road works
into account that are up to 60 days in the future.
Default value: true |
---|
avoid
string
| Specifies something that the route calculation should try to avoid when
determining the route. The avoid can be specified multiple
times (e.g.,
...&avoid=motorways&avoid=ferries&... ).
Possible values are: tollRoads : Avoids toll roads.
motorways : Avoids motorways.
ferries : Avoids ferries.
unpavedRoads : Avoids unpaved roads.
carpools : Avoids routes that require use of carpool
(HOV/High Occupancy Vehicle) lanes.
alreadyUsedRoads :
borderCrossings : Avoids crossing country borders.
tunnels : Avoids tunnels.
carTrains : Avoids car trains.
lowEmissionZones : Avoids low-emission zones.
Note: In calculateReachableRange requests, the value alreadyUsedRoads must not be used. |
---|
prefer
string
| Specifies something that the route calculation should try to prefer when
determining the route.
Possible value: |
---|
handsFreeDrivingCapability
string
| Specifies the hands-free driving capability of the vehicle.
The available hands-free driving data is matched against handsFreeDrivingCapability
in order to filter for the subset of data that applies to the specific capability of the vehicle. Must be used together with prefer=handsFreeDriving . The value must match the regular expression
'^[a-zA-Z0-9-:]{1,100}$' .
|
---|
travelMode
string
| The mode of travel for the requested route. Note that the requested travelMode may not be available
for the entire route. Where the requested travelMode is not available for a
particular section, the travelMode field of the
response for that section will be set to "other".
Note that travel modes bus , motorcycle ,
taxi , and van are in BETA functionality. Default value: car
Other values: truck taxi bus van motorcycle bicycle pedestrian
|
---|
hilliness
string
| Degree of hilliness for a thrilling route.
Note: This parameter can only be used in conjunction with
routeType=thrilling .
Default value: normal
Other values: |
---|
windingness
string
| Level of turns for thrilling route.
Note: This parameter can only be used in conjunction with
routeType=thrilling .
Default value: normal
Other values: |
---|
vehicleMaxSpeed
integer
| Maximum speed of the vehicle in kilometers/hour. Must have a value in the range [0, 250] . A value of 0 means that an appropriate value for the
vehicle will be determined and applied during route planning.
Default value: 0 |
---|
vehicleWeight
integer
| Weight of the vehicle in kilograms. If a detailed Consumption model is specified, refer to the following Consumption model parameters section for the documentation of vehicleWeight . If a detailed Consumption model is not specified, and the value of
vehicleWeight is non-zero, then weight restrictions are
considered. - In all other cases, this parameter is ignored.
Default value: 0 |
---|
vehicleAxleWeight
integer
| Weight per axle of the vehicle in kilograms. A value of
0 means that weight restrictions per axle are not
considered.
Default value: 0 |
---|
vehicleNumberOfAxles
integer
| Number of axles of the vehicle. A value of 0 means that
the number of axles restrictions are not considered.
Default value: 0 |
---|
vehicleLength
float
| Length of the vehicle in meters, including the length of any additional
equipment, e.g., trailers, bike racks, etc. A value of 0
means that length restrictions are not considered. Fractional digits are
rounded to the closest centimeter while rounding up on a tie.
Default value: 0 |
---|
vehicleWidth
float
| Width of the vehicle in meters. A value of 0 means that
width restrictions are not considered. Fractional digits are
rounded to the closest centimeter while rounding up on a tie.
Default value: 0 |
---|
vehicleHeight
float
| Height of the vehicle in meters. A value of 0 means that
height restrictions are not considered. Fractional digits are
rounded to the closest centimeter while rounding up on a tie.
Default value: 0 |
---|
vehicleCommercial
boolean
| Vehicle is used for commercial purposes and thus may not be allowed to
drive on some roads.
Default value: false |
---|
vehicleLoadType
string
| Specifies types of cargo that may be classified as hazardous materials
and are restricted from some roads. The vehicleLoadType
parameter can be specified multiple times (e.g., ...&vehicleLoadType=USHazmatClass1&vehicleLoadType=USHazmatClass2&vehicleLoadType=USHazmatClass3&...
or ...&vehicleLoadType=otherHazmatExplosive&vehicleLoadType=otherHazmatHarmfulToWater&...
).
Available values are: - US Hazmat classes 1 through 9
- Generic classifications for use in other countries.
Use these values for routing in the USA: USHazmatClass1 : Explosives
USHazmatClass2 : Compressed gas
USHazmatClass3 : Flammable liquids
USHazmatClass4 : Flammable solids
USHazmatClass5 : Oxidizers
USHazmatClass6 : Poisons
USHazmatClass7 : Radioactive
USHazmatClass8 : Corrosives
USHazmatClass9 : Miscellaneous
Use these values for routing in all other countries: otherHazmatExplosive : Explosives
otherHazmatGeneral : Miscellaneous
otherHazmatHarmfulToWater : Harmful to water
Notes: If travelMode is pedestrian or
bicycle ,vehicleLoadType is not considered. The vehicleLoadType and
vehicleAdrTunnelRestrictionCode
parameters are independent; please provide both if applicable.
|
---|
vehicleAdrTunnelRestrictionCode
string
| If vehicleAdrTunnelRestrictionCode is specified, the
vehicle is subject to ADR tunnel restrictions. Vehicles with code B are restricted from roads with ADR
tunnel categories B, C, D, and E. Vehicles with code C are restricted from roads with ADR
tunnel categories C, D, and E. Vehicles with code D are restricted from roads with ADR
tunnel categories D and E. Vehicles with code E are restricted from roads with ADR
tunnel category E. If vehicleAdrTunnelRestrictionCode is not specified, no
ADR tunnel restrictions apply.
Notes: If travelMode is pedestrian or
bicycle , vehicleAdrTunnelRestrictionCode is
not considered. The vehicleAdrTunnelRestrictionCode and
vehicleLoadType
parameters are independent; please provide both if applicable.
Values (specify at most one): Reference: |
---|
coordinatePrecision
string
| Specifies the precision of coordinates in the response.
Possible values are: default : All coordinates are rounded to 5 digits after
the decimal point. Default precision coordinates are targeted
towards clients that are sensitive to response sizes. This should be
sufficient for most applications.
full : All coordinates are rounded to 7 digits after the
decimal point. Full precision coordinates are targeted towards
applications that require precise polyline visualization at high
zoom levels.
Default value: default
Other value: full |
---|
reconstructionMode
string
| Specifies how to reconstruct a given route.
Note: this parameter can only be used when a route is provided as part
of the request by using supportingPoints . For a description
of supportingPoints see the Post Data section of the
Calculate Route or
Calculate Reachable Range document.
Possible values are: normal : Some leeway is allowed when the provided route polyline doesn't
exactly match the road network, such that a most sensible route is reconstructed.
Use this option in case the given polyline comes from a third party source
such as a recorded track, a different routing service, or user input.
strict : Reconstruct the given route as close as possible to the given
route polyline. This might mean that some driving restrictions are violated in order to closely match the original route.
Use this option when reconstructing a route previously received from this service.
Default value: normal
Other value: strict |
---|
arrivalSidePreference
string
| Specifies the preference of roadside on arrival to waypoints and destination. Stop on the road has to be set at least two meters to the preferred side,
otherwise the behavior will default to "anySide".
Possible values are: anySide : Both sides of a road could be used to approach the waypoint and destination. When a vehicle arrives, a stop
could be either on a left side or a right side.
curbSide : Ensures a minimal number of road crossings at waypoints or the destination. When a vehicle
arrives, a stop should be on the right for the right-side driving road or on a left for the left-side driving road.
Default value: anySide
Other value: curbSide |
---|
Section 2. Consumption model parameters
Routing provides a set of parameters for a detailed description of a vehicle-specific Consumption model.
- These parameters can be specified in a
calculateRoute
request.
- They must be specified in a
calculateReachableRange
request.
Depending on the value of vehicleEngineType
, we support two principal Consumption models:
- Combustion consumption model
- Electric consumption model
Note:
- Specifying parameters that belong to different models in the same request is an error.
- A Consumption model cannot be used with the
travelMode
values of bicycle
and pedestrian
.
Parameter constraints
In both Consumption models, explicitly specifying some parameters requires specifying some others as well. In addition, some parameters are mutually exclusive. These are the constraints:
- All parameters require
constantSpeedConsumption*
to be specified by the user.
- It is an error to specify any other Consumption model parameter (with the exception of
vehicleWeight
) if constantSpeedConsumption*
is not specified.
accelerationEfficiency
and decelerationEfficiency
must always be specified as a pair (i.e., both or none).
- If
accelerationEfficiency
and decelerationEfficiency
are specified, the product of their values must not be greater than 1
(to prevent perpetual motion).
uphillEfficiency
and downhillEfficiency
must always be specified as a pair (i.e., both or none).
- If
uphillEfficiency
and downhillEfficiency
are specified, the product of their values must not be greater than 1
(to prevent perpetual motion).
consumptionInkWhPerkmAltitudeGain
and recuperationInkWhPerkmAltitudeLoss
must always be specified as a pair (i.e., both or none).
- If they are specified,
recuperationInkWhPerkmAltitudeLoss
must not be greater than consumptionInkWhPerkmAltitudeGain
(to prevent perpetual motion).
- If
*Efficiency
parameters are specified by the user, then vehicleWeight
must also be specified.
- When
vehicleEngineType
is combustion
, fuelEnergyDensityInMJoulesPerLiter
must be specified as well.
- If
*Efficiency
parameters are specified by the user, then consumptionInkWhPerkmAltitudeGain
and recuperationInkWhPerkmAltitudeLoss
cannot be specified.
maxChargeInkWh
and currentChargeInkWh
must always be specified as a pair (i.e., both or none).
Note that if only constantSpeedConsumption*
is specified, no other consumption aspects are taken into account, i.e., slopes and vehicle acceleration are not considered for consumption computations.
Selecting the Consumption model
There are two available Consumption models: Combustion and Electric.
- A model is selected by specifying the corresponding
constantSpeedConsumption*
parameter and possibly further parameters that belong to the same model.
- The chosen model must match the value of the
vehicleEngineType
parameter.
Optional parameter | Description |
---|
vehicleEngineType
string
| The engine type of the vehicle. When a detailed Consumption model is
specified, it must be consistent with the value of
vehicleEngineType .
Default value: combustion
Other value: electric |
---|
The Combustion consumption model
Details
The Combustion consumption model is used when the vehicleEngineType
value is set to combustion
. The following data table describes all of the parameters that can be specified in a request using the Combustion model.
- Required parameters must be used or the call will fail.
- Optional parameters may be used.
- The order of parameters in a request is not important.
Required parameters | Description |
---|
constantSpeedConsumptionInLitersPerHundredkm
Colon-delimited list of CombustionConstantSpeedConsumptionPair
| Specifies the speed-dependent component of consumption. Consumption rates for speeds not in the list are found as follows: By linear interpolation, if the given speed lies in between two
speeds in the list. By linear extrapolation otherwise, assuming a constant (
ΔConsumption /ΔSpeed )
determined by the nearest two points in the list.
The list must contain between 1 and 25 points (inclusive), and may not
contain duplicate points for the same speed. Consumption specified for the largest speed must be greater than or equal
to that of the penultimate largest speed. This ensures that extrapolation does not lead to negative
consumption rates. Similarly, consumption values specified for the two smallest speeds
in the list cannot lead to a negative consumption rate for any
smaller speed. The minimum and maximum values described here refer to the valid
range for the consumption values (expressed in l/100km).
Minimum value: 0.01
Maximum value: 100000.0 |
---|
Optional parameters | Description |
---|
vehicleWeight
integer
| Weight of the vehicle in kilograms.
Note: it is mandatory if any of the Efficiency parameters are set. Minimum value: 1 |
---|
currentFuelInLiters
float
| Specifies the current supply of fuel in liters.
Minimum value: 0.0 |
---|
auxiliaryPowerInLitersPerHour
float
| Specifies the amount of fuel consumed for sustaining auxiliary systems
of the vehicle, in liters per hour. It can be used to specify
consumption due to devices and systems such as AC systems, radio,
heating, etc.
Minimum value: 0.0 |
---|
fuelEnergyDensityInMJoulesPerLiter
float
| Specifies the amount of chemical energy stored in one liter of fuel in
megajoules (MJ). It is used in conjunction with the Efficiency parameters for
conversions between saved or consumed energy and fuel. For example, energy density is 34.2 MJ/l for gasoline, and 35.8 MJ/l
for Diesel fuel. This parameter must be used/required if any *Efficiency parameter is
set.
Minimum value: 1.0 |
---|
accelerationEfficiency
float
| Note: This must be paired with decelerationEfficiency . - Specifies the efficiency of converting chemical energy stored in fuel to
kinetic energy when the vehicle accelerates, (i.e.,
KineticEnergyGained /ChemicalEnergyConsumed ). ChemicalEnergyConsumed is obtained by converting consumed fuel to chemical energy using fuelEnergyDensityInMJoulesPerLiter .
Minimum value: 0.0
Maximum value: 1/decelerationEfficiency |
---|
decelerationEfficiency
float
| Note: This must be paired with accelerationEfficiency . - Specifies the efficiency of converting kinetic energy to saved (not
consumed) fuel when the vehicle decelerates (i.e.,
ChemicalEnergySaved /KineticEnergyLost ). ChemicalEnergySaved is obtained by converting saved (not consumed) fuel to energy using fuelEnergyDensityInMJoulesPerLiter .
Minimum value: 0.0
Maximum value: 1/accelerationEfficiency |
---|
uphillEfficiency
float
| Note: This must be paired with downhillEfficiency . - Specifies the efficiency of converting chemical energy stored in fuel to
potential energy when the vehicle gains elevation, (i.e.,
PotentialEnergyGained /ChemicalEnergyConsumed ). ChemicalEnergyConsumed is obtained by converting
consumed fuel to chemical energy using
fuelEnergyDensityInMJoulesPerLiter .
Minimum value: 0.0
Maximum value: 1/downhillEfficiency |
---|
downhillEfficiency
float
| Note: This must be paired with uphillEfficiency . - Specifies the efficiency of converting potential energy to saved (not
consumed) fuel when the vehicle loses elevation, (i.e.,
ChemicalEnergySaved /PotentialEnergyLost ). ChemicalEnergySaved is obtained by converting saved
(not consumed) fuel to energy using
fuelEnergyDensityInMJoulesPerLiter .
Minimum value: 0.0
Maximum value: 1/uphillEfficiency |
---|
The Electric Consumption model
Details
The Electric Consumption model is used when vehicleEngineType
is set to electric.
The following data table describes all of the parameters that can be specified in a request using the Electric model.
- Required parameters must be used or the call will fail.
- Optional parameters may be used.
- The order of parameters in a request is not important.
Required parameters | Description |
---|
constantSpeedConsumptionInkWhPerHundredkm
Colon-delimited list of ElectricConstantSpeedConsumptionPair
| Specifies the speed-dependent component of consumption. Consumption rates for speeds not in the list are found as follows: By linear interpolation, if the given speed lies in between two
speeds in the list. By linear extrapolation otherwise, assuming a constant (
ΔConsumption /ΔSpeed )
determined by the nearest two points in the list.
The list must contain between 1 and 25 points (inclusive), and may not
contain duplicate points for the same speed. If it only contains a single point, then the consumption rate of
that point is used without further processing. Consumption specified for the largest speed must be greater than or
equal to that of the penultimate largest speed. This ensures that
extrapolation does not lead to negative consumption rates. Similarly, consumption values specified for the two smallest speeds
in the list cannot lead to a negative consumption rate for any
smaller speed. The minimum and maximum values described here refer
to the valid range for the consumption values (expressed in
kWh/100km).
Minimum value: 0.01
Maximum value: 100000.0 |
---|
vehicleWeight
integer
| Note: This is only required if any *Efficiency parameter is set. Minimum value: 1 |
---|
Optional parameters | Description |
---|
currentChargeInkWh
float
| Specifies the current electric energy supply in kilowatt hours (kWh).
Note: Requires maxChargeInkWh to be set.
Minimum value: 0.0
Maximum value: maxChargeInkWh |
---|
maxChargeInkWh
float
| Specifies the maximum electric energy supply in kilowatt hours (kWh)
that may be stored in the vehicle's battery.
Note: Requires currentChargeInkWh to be set.
Minimum value: currentChargeInkWh |
---|
auxiliaryPowerInkW
float
| Specifies the amount of power consumed for sustaining auxiliary systems,
in kilowatts (kW). It can be used to specify consumption due to devices
and systems such as AC systems, radio, heating, etc.
Minimum value: 0.0 |
---|
accelerationEfficiency
float
| Specifies the efficiency of converting electric energy to kinetic energy
when the vehicle accelerates (i.e., KineticEnergyGained /
ElectricEnergyConsumed ).
Notes: - It must be paired with
decelerationEfficiency . - It cannot be used with
consumptionInkWhPerkmAltitudeGain or
recuperationInkWhPerkmAltitudeLoss .
Minimum value: 0.0
Maximum value: 1/decelerationEfficiency |
---|
decelerationEfficiency
float
| Specifies the efficiency of converting kinetic energy to electric energy
when the vehicle decelerates (i.e., ElectricEnergyGained /
KineticEnergyLost ).
Notes: Minimum value: 0.0
Maximum value: 1/accelerationEfficiency |
---|
uphillEfficiency
float
| Specifies the efficiency of converting electric energy to potential
energy when the vehicle gains elevation (i.e.,
PotentialEnergyGained /ElectricEnergyConsumed ).
Notes: Minimum value: 0.0
Maximum value: 1/downhillEfficiency |
---|
downhillEfficiency
float
| Specifies the efficiency of converting potential energy to electric
energy when the vehicle loses elevation (i.e,
ElectricEnergyGained /PotentialEnergyLost ).
Notes: Minimum value: 0.0
Maximum value: 1/uphillEfficiency |
---|
consumptionInkWhPerkmAltitudeGain
float
| Specifies the electric energy in kWh consumed by the vehicle through
gaining 1000 meters of elevation.
Notes: It must be paired with
recuperationInkWhPerkmAltitudeLoss . It cannot be used with accelerationEfficiency ,
decelerationEfficiency , uphillEfficiency
or downhillEfficiency .
Minimum value: recuperationInkWhPerkmAltitudeLoss
Maximum value: 500.0 |
---|
recuperationInkWhPerkmAltitudeLoss
float
| Specifies the electric energy in kWh gained by the vehicle through
losing 1000 meters of elevation.
Notes: It must be paired with
consumptionInkWhPerkmAltitudeGain . It cannot be used with accelerationEfficiency ,
decelerationEfficiency , uphillEfficiency
or downhillEfficiency .
Minimum value: 0.0
Maximum value: consumptionInkWhPerkmAltitudeGain |
---|
Sensible values of consumption parameters
Details
It is possible that a particular set of consumption parameters is rejected, even though it might fulfill all the explicit requirements specified above. This will happen when the value of a specific parameter, or a combination of values of several parameters, is deemed to lead to unreasonable magnitudes of consumption values.
If that happens, it most likely indicates an input error, as proper care is taken to accommodate all sensible values of consumption parameters. In case a particular set of consumption parameters is rejected, the accompanying error message will contain a textual explanation of the reason(s).
Example
To give the feeling of the magnitudes of reasonable parameter values, the following data table provides an example of sensible values for the Combustion and Electric models.
Parameter | Sensible values by model |
---|
constantSpeedConsumptionInLitersPerHundredkm
Colon-delimited list of CombustionConstantSpeedConsumptionPair
| |
---|
constantSpeedConsumptionInkWhPerHundredkm
Colon-delimited list of ElectricConstantSpeedConsumptionPair
| |
---|
vehicleWeight
integer
| Combustion model: 1600 Electric model: 1900
|
---|
currentFuelInLiters
integer
| Combustion model: 55 - Electric model: -
|
---|
currentChargeInkWh
float
| - Combustion model: -
Electric model: 43
|
---|
maxChargeInkWh
float
| - Combustion model: -
Electric model: 85
|
---|
auxiliaryPowerInLitersPerHour
float
| Combustion model: 0.2 - Electric model: -
|
---|
auxiliaryPowerInkW
float
| - Combustion model: -
Electric model: 1.7
|
---|
fuelEnergyDensityInMJoulesPerLiter
float
| Combustion model: 34.2 - Electric model: -
|
---|
accelerationEfficiency
float
| Combustion model: 0.33 Electric model: 0.66
|
---|
decelerationEfficiency
float
| Combustion model: 0.83 Electric model: 0.91
|
---|
uphillEfficiency
float
| Combustion model: 0.27 Electric model: 0.74
|
---|
downhillEfficiency
float
| Combustion model: 0.51 Electric model: 0.73
|
---|
consumptionInkWhPerkmAltitudeGain
float
| - Combustion model: -
Electric model: 7.0
|
---|
recuperationInkWhPerkmAltitudeLoss
float
| - Combustion model: -
Electric model: 3.8
|
---|
POST data parameters
Details
Some parameters can be provided using the HTTP POST
method.
- The POST data should be in JSON format, see the Content-Type header.
- All POST data parameters are optional.
- It is an error to use the HTTP POST method if no POST data parameters are provided.
There is an upper limit on the total size of the POST data.
- Exceeding this limit results in a response with the response code
413
, indicating invalid POST data.
- The client must not rely on the exact value of this limit.
- The current limit is 10 MB.
The following table describes a subset of the parameters that can be used in the Calculate Route and Calculate Reachable Range services.
Parameter | Description |
---|
avoidVignette
array
| This is an array of strings. Each string should be a 3-character, ISO
3166-1, alpha-3 country code. Note: It is an error to specify both avoidVignette and
allowVignette . |
---|
allowVignette
array
| This is an array of strings. Each string should be a 3-character, ISO
3166-1, alpha-3 country code. The array describes the countries in which toll roads with vignettes
are allowed. Specifying allowVignette with an array of countries is
equivalent to specifying avoidVignette with the array
of all countries other than those specified in
allowVignette . Specifying allowVignette with an empty array is the
same as avoiding all toll roads with vignettes.
Note: It is an error to specify both avoidVignette and
allowVignette . |
---|
avoidAreas
object
| Defines areas of certain shapes to avoid when planning routes. Supported
shapes include rectangles . It can contain one of each
supported shapes fields. |
---|
rectangles
array
| This is an array of objects, with a maximum of ten elements. Each object
describes an axis-aligned rectangle, defined using the fields
southWestCorner and northEastCorner . - The maximum size of a rectangle is about 160x160 km.
- It cannot cross the 180th meridian.
- It must be between -80 and +80 degrees of latitude.
|
---|
southWestCorner
object
| The south-west corner of a rectangle. It is an object consisting of a
latitude and a longitude field, each field
containing the value in degrees as a number. |
---|
northEastCorner
object
| The north-east corner of a rectangle. It is an object consisting of a
latitude and a longitude field, each field
containing the value in degrees as a number. |
---|
Avoiding roads with usage-based toll collection
There is special behavior where only roads with usage-based toll collection could be avoided.
Scenario 1:
avoid = tollRoad
"allowVignette": [value]
Result:
Roads with usage-based toll collection are avoided. Toll roads requiring vignettes are also avoided,
except in selected countries (marked as value
above) where toll roads with vignettes are allowed.
Note:
in this scenario avoidVignette
has to be None
.
Scenario 2:
avoid = tollRoad
"avoidVignette": [value]
Result:
Roads with usage-based toll collection are avoided. Toll roads requiring vignettes are allowed, except
in selected countries (marked as value
above) where toll roads with vignettes are avoided.
Note:
in this scenario allowVignette
has to be None
.
Request content example
post
Request content example
2 "avoidVignette": ["AUS", "CHE"],
Response data
The following data table describes HTTP response headers of particular interest to Calculate Route and Calculate Reachable Range service clients.
Header | Description |
---|
Access-Control-Expose-Headers | The service whitelists response headers that browsers are allowed to
access.
Value: Content-Length |
---|
Access-Control-Allow-Origin | The service allows cross-origin resource sharing.
Value: * (wildcard) |
---|
Content-Encoding | The service supports HTTP compression, if requested by the client.
Value: gzip |
---|
Content-Type | The format of the response. The service supports specifying the desired
response format. See the contentType parameter.
Values: application/json; charset=utf-8 application/javascript; charset=utf-8
|
---|
Cache-Control | The Cache-Control general-header field is used to specify directives
that must be obeyed by all caching mechanisms along the request/response
chain. It is supported by HTTP/1.1 clients. It may not be supported by
HTTP/1.0 clients.
Values: |
---|
Pragma | The Pragma general-header field is used to specify directives that might
apply to any recipient along the request/response chain. It is supported
by HTTP/1.0 client.
Value: no-cache |
---|
Tracking-ID | This is an identifier for the request. If Tracking-ID was
specified in the request headers, it contains the same value. Otherwise
it may contain a generated value. |
---|
Warning | This may be sent for deprecated features. |
---|
Response codes
The following table describes HTTP response codes of particular interest to Calculate Route and Calculate Reachable Range service clients.
Code | Meaning & possible causes |
---|
200 | OK: A route or range was calculated and the body of the response
contains the data for a successful response. |
---|
400 | Bad request: One or more parameters were: |
---|
403 | Permission, capacity, or authentication issues: - Forbidden
- Not authorized
- Account inactive
- Account over queries per second limit
|
---|
404 | Not Found: The requested resource could not be found, but it may
be available again in the future. |
---|
405 | Method Not Allowed: The client used a HTTP method other than GET
or POST. |
---|
408 | Request timeout: The client took too long to transmit the
request. |
---|
414 | Requested uri is too long. |
---|
415 | Unsupported Media Type. |
---|
429 | Too Many Requests: Too many requests were sent in a given amount
of time for the supplied API Key. |
---|
500 | An error occurred while processing the request. Please try again
later. This can also indicate that the request reached an internal computation
time threshold and timed out. |
---|
502 | Internal network connectivity issue. |
---|
503 | Service currently unavailable. |
---|
504 | Internal network connectivity issue. |
---|
596 | Service not found. |
---|