TomTom LogoDocs
Products
Resources
Pricing
Sign in
Reachable Range API
Documentation
API Explorer

Calculate Reachable Range

Service version: 1Last edit: 2026.08.17TomTom Maps

Purpose

The Calculate Reachable Range service calculates the geographic area that can be reached from the origin point.

  • It optimizes routes with a given route type (for example, fastest, eco).
  • It limits the range based on the given budget and consumption parameters.

The information returned is:

  • A polygon boundary in counterclockwise orientation.
  • The precise polygon center (the result of map-matching the origin point).

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

Request data

HTTPS method: GET   POST

Constants and parameters enclosed in curly brackets { } must be replaced with their values.

Generic request format

The following request URL contains all of this endpoint’s parameters. For required and optional parameters, see the following sections:

get
Request example
https://{baseURL}/routing/{versionNumber}/calculateReachableRange/{origin}/{contentType}?key={Your_API_Key}
&callback={callback}
&fuelBudgetInLiters={float}
&energyBudgetInkWh={float}
&timeBudgetInSec={float}
&distanceBudgetInMeters={float}
&report={effectiveSettings}
&departAt={time}
&routeType={routeType}
&traffic={boolean}
&avoid={avoidType}
&maxFerryLengthInMeters={float}
&smoothing={smoothingLevel}
&travelMode={travelMode}
&hilliness={hilliness}
&windingness={windingness}
&vehicleMaxSpeed={vehicleMaxSpeed}
&vehicleWeight={vehicleWeight}
&vehicleAxleWeight={vehicleAxleWeight}
&vehicleNumberOfAxles={vehicleNumberOfAxles}
&vehicleLength={vehicleLength}
&vehicleWidth={vehicleWidth}
&vehicleHeight={vehicleHeight}
&vehicleCommercial={boolean}
&vehicleLoadType={vehicleLoadType}
&vehicleAdrTunnelRestrictionCode={vehicleAdrTunnelRestrictionCode}
&vehicleEngineType={vehicleEngineType}
&constantSpeedConsumptionInLitersPerHundredkm={CombustionConstantSpeedConsumptionPairs}
&currentFuelInLiters={float}
&auxiliaryPowerInLitersPerHour={float}
&fuelEnergyDensityInMJoulesPerLiter={float}
&accelerationEfficiency={float}
&decelerationEfficiency={float}
&uphillEfficiency={float}
&downhillEfficiency={float}
&consumptionInkWhPerkmAltitudeGain={float}
&recuperationInkWhPerkmAltitudeLoss={float}
&constantSpeedConsumptionInkWhPerHundredkm={ElectricConstantSpeedConsumptionPairs}
&currentChargeInkWh={float}
&maxChargeInkWh={float}
&auxiliaryPowerInkW={float}

GET URL example

Note: Linebreaks are designated by ”\”.

get
GET request example
https://api.tomtom.com/routing/1/calculateReachableRange/52.50931,13.42936/json?\
fuelBudgetInLiters=50&report=effectiveSettings\
&routeType=eco&traffic=true&avoid=unpavedRoads&travelMode=car&vehicleMaxSpeed=120\
&vehicleCommercial=false&vehicleEngineType=combustion\
&constantSpeedConsumptionInLitersPerHundredkm=50%2C8.2%3A130%2C21.3&key={Your_API_Key}

GET curl command example

Note: Linebreaks are designated by ”\”.

get
GET curl command example
curl -X GET "https://api.tomtom.com/routing/1/calculateReachableRange/52.50931,13.42936/json?\
energyBudgetInkWh=50&report=effectiveSettings\
&routeType=eco&traffic=true&avoid=unpavedRoads&travelMode=car&vehicleMaxSpeed=120\
&vehicleCommercial=false&vehicleEngineType=electric\
&constantSpeedConsumptionInkWhPerHundredkm=50%2C8.2%3A130%2C21.3\
&key={Your_API_Key}" -H "accept: */*"

POST URL example

Note: Linebreaks are designated by ”\”.

post
POST URL request example
https://api.tomtom.com/routing/1/calculateReachableRange/52.50931,13.42936/json?\
energyBudgetInkWh=50&report=effectiveSettings\
&routeType=eco&traffic=true&avoid=unpavedRoads&travelMode=car&vehicleMaxSpeed=120\
&vehicleCommercial=false&vehicleEngineType=electric\
&constantSpeedConsumptionInkWhPerHundredkm=50%2C8.2%3A130%2C21.3\
&key={Your_API_Key}

POST curl command examples

Note: Linebreaks are designated by ”\”.

post
POST curl command example
curl -X POST "https://api.tomtom.com/routing/1/calculateReachableRange/52.50931,13.42936/json?energyBudgetInkWh=43&report=effectiveSettings&routeType=eco&traffic=true&avoid=unpavedRoads&travelMode=car&vehicleMaxSpeed=120&vehicleCommercial=false&vehicleEngineType=electric&constantSpeedConsumptionInkWhPerHundredkm=50%2C8.2%3A130%2C21.3&key={Your_API_Key}"\
 -H "accept: */*" -H "Content-Type: application/json" -d\
'{
  "supportingPoints": [
    {
      "latitude": 52.50931,
      "longitude": 13.42936
    },
    {
      "latitude": 52.50872,
      "longitude": 13.42900
    },
    {
      "latitude": 52.50844,
      "longitude": 13.42859
    }
  ],
  "avoidVignette":[
    "AUS","CHE"
  ],
  "avoidAreas":{
    "rectangles":[
    {
      "southWestCorner":{
       "latitude":48.81851,"longitude":2.26593
       },
      "northEastCorner":{
       "latitude":48.90309,"longitude":2.41115
       }
     }
    ]
  }
}'
post
POST curl command example with encoded polyline
curl -X POST "https://api.tomtom.com/routing/1/calculateReachableRange/52.50931,13.42936/json?energyBudgetInkWh=43&report=effectiveSettings&routeType=eco&traffic=true&avoid=unpavedRoads&travelMode=car&vehicleMaxSpeed=120&vehicleCommercial=false&vehicleEngineType=electric&constantSpeedConsumptionInkWhPerHundredkm=50%2C8.2%3A130%2C21.3&key={Your_API_Key}"\
 -H "accept: */*" -H "Content-Type: application/json" -d\
'{
  "encodedPolyline": "evn_Io|}pAtBfAv@pA",
  "encodedPolylinePrecision": 5,
  "avoidVignette":[
    "AUS","CHE"
  ],
  "avoidAreas":{
    "rectangles":[
    {
      "southWestCorner":{
       "latitude":48.81851,"longitude":2.26593
       },
      "northEastCorner":{
       "latitude":48.90309,"longitude":2.41115
       }
     }
    ]
  }
}'

Types

The following data table describes the types that can be used in the Calculate Reachable Range service.

Type

Description

location
string

A 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 two fields: latitude and longitude, each containing a number. Both values must use the same reference frame and follow the same constraints as 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)

A comma-separated speedInkmh,consumptionInLitersPerHundredkm pair. Constraint: speedInkmh must be in the range [0.0, 255.0].
Example: 15.5,10.0

ElectricConstantSpeedConsumptionPair
string (contains a pair of two, comma-separated floats)

A comma-separated speedInkmh,consumptionInkWhPerHundredkm pair. Constraint: speedInkmh must be in the range [0.0, 255.0].
Example: 15.5,8.0

Avoid parameter possible values

Value

Description

tollRoads

Avoids toll roads.

motorways

Avoids motorways.

Note: Avoiding motorways for long routes of approximately 500km+ may result in computation timeouts of the primary route or path alternatives.

ferries

Avoids ferries.

unpavedRoads

Avoids unpaved roads.

carpools

Avoids routes that require use of carpool (HOV/High Occupancy Vehicle) lanes.

borderCrossings

Avoids crossing country borders.

tunnels

Avoids tunnels.

carTrains

Avoids car trains.

lowEmissionZones

Avoids low-emission zones.

In calculateReachableRange requests, the value alreadyUsedRoads must not be used.

Request headers

The following table describes the supported HTTP request headers.

  • Required headers must be used; otherwise, the call will fail.
  • Optional headers can be used to customize the request.
  • 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 compression used for 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:

  • identity
  • gzip
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

The following table describes the base path parameters that can be used in the Calculate Reachable Range service.

  • Required parameters must be used or the call will fail.
  • The order of the required parameters is important and must be followed.

Required parameters (base path)

Description

baseURL
string

The base URL used to call the API.


Values:

  • api.tomtom.com: The default global API endpoint.

  • kr-api.tomtom.com: The region-specific endpoint for South Korea. See the Region-specific content documentation.

versionNumber
integer

The service version number.


Value: The current value is 1.

origin
location

Location from which the range calculation should start, in the form of a location. See the Types section for the format and possible values.

contentType
string

The content type of the response structure.


Possible values:

  • json
  • jsonp

Note: If the content type is jsonp, a callback method can be specified in the query parameters.

Request parameters

The following table describes the parameters that can be used in the Calculate Reachable Range service.

  • Required parameters must be used, or the call will fail.
  • Optional parameters may be omitted, except under the specified conditions.
  • The order of request parameters is not important.
  • Exactly one budget (fuelBudgetInLiters, energyBudgetInkWh, timeBudgetInSec, or distanceBudgetInMeters) must be used.
  • When fuelBudgetInLiters or energyBudgetInkWh is used, it is mandatory to specify a detailed Consumption Model.

Required parameters

Description

key
string

The API key used to authorize requests to the API.
Value: Your valid API Key.

Optional parameters

Description

fuelBudgetInLiters
float

Fuel budget in liters that determines the maximum range that can be traveled using the specified Combustion Consumption Model.


Minimum value:0

Maximum value: 10000, but no more than currentFuelInLiters (if it’s specified)

  • When fuelBudgetInLiters is used, it is mandatory to specify a detailed Combustion Consumption Model.

energyBudgetInkWh
float

Electric energy budget in kilowatt-hours (kWh) that determines the maximum range that can be traveled using the specified Electric Consumption Model.


Minimum value:0

Maximum value: 10000, but no more than currentChargeInkWh (if it’s specified)

  • When energyBudgetInkWh is used, it is mandatory to specify a detailed Electric Consumption Model.

timeBudgetInSec
float

The time budget in seconds that determines the maximal range which can be traveled. The Consumption Model will only affect the range when routeType is eco.
Minimum value: 0


Maximum value:10000000
distanceBudgetInMeters
float

The distance budget in meters that determines the maximal range which can be traveled. The Consumption Model will only affect the range when routeType is eco.
Minimum value: 0


Maximum value:50000000
maxFerryLengthInMeters
float

The limit (in meters) for a single ferry connection to be included in the range calculation.


The entire length of a ferry connection must be shorter than this distance for any part of the connection to be considered for the calculation. The value is exclusive: ferry connections greater than or equal to this distance are ignored. Setting maxFerryLengthInMeters to 0 excludes all ferry connections.


Minimum value:0
Maximum value:20000
Default value:20000
smoothing
string

Applies a post processing step that smooths the reachable-range polygon boundary to improve its visual appearance. Stronger smoothing generally results in more points.


Possible values are:

  • none: has no effect, no smoothing is applied.

  • weak: applies weak smoothing. The exact method is subject to change.

  • strong: applies strong smoothing. The exact method is subject to change.


Default value:none
callback
string

Specifies the jsonp callback method. Only used when contentType is jsonp.


Default value:callback
report
string

Specifies which data to report for diagnostic purposes. Possible value is: effectiveSettings.

  • Reports the effective parameters or data used when calling the API.

  • For defaulted parameters, the returned value reflects the default if the parameter was not specified.

Default value:effectiveSettings
departAt
string

The date and time of departure from the origin point.

  • Departure times other than now must be specified as a dateTime.

  • If no time zone offset is provided, the origin point’s time zone is assumed.

Default value:now
Other value:dateTime
routeType
string

Specifies the type of optimization used when calculating routes. (In the case of Calculate Reachable Range, this refers to the routes on which the reachable-range calculation is based. The range will indicate the geographic area that can be reached on routes optimized according to this routeType. Note that the budget type can be selected independently of the routeType optimization.)


Possible values:

  • fastest: Route calculation is optimized for travel time while keeping routes sensible. For example, the calculation may avoid shortcuts along inconvenient side roads or long detours that save very little time.

  • shortest: Route calculation is optimized for travel distance while keeping the routes sensible. For example, straight routes are preferred over those with many turns.

    • Use shortest only for short to medium-distance routes. It explores a much larger search space than fastest, so on long-distance routes — especially when combined with waypoints or avoid options — it can exceed the server’s compute time limit and the request will fail with a timeout. For long-distance planning, use fastest instead.

  • short: Route calculation aims to strike a good balance between shorter travel time and shorter travel distance.

  • eco: Route calculation aims to strike a good balance between shorter travel time and lower fuel or energy consumption.

  • thrilling: Route calculation is optimized to include interesting or challenging roads and to use as few motorways as possible.

    • You can configure the level of turns and the degree of hilliness.

    • Use the hilliness and windingness parameters to set this.

    • There is a limit of 900 km on routes planned with routeType=thrilling.

Default value:fastest
coordinatePrecision
string

Specifies the precision of coordinates in the response.


Possible values:

  • 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
reconstructionMode
string

Specifies how to reconstruct a route provided with the request. The reconstructed route is used internally to keep the reachable-range polygon consistent with a specific route — see the POST data parameters section.


Note: This parameter can only be used when a route is provided as part of the request by using a polyline representation format (see the Route geometry representation formats section).


Possible values:

  • normal: Some leeway is allowed when the provided polyline doesn’t exactly match the road network, so that the 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. Consider using the track mode, which is newer and gives better results.

  • strict: Reconstruct the given route as close as possible to the given 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.

  • track: This mode provides flexibility when the provided route polyline does not align well with the road network, allowing the reconstruction of the most sensible route. The input polyline may have inconsistencies such as gaps and loops. When reconstructing the route using track mode, the algorithm will try to respect the driving restrictions and consider traffic conditions. Use this mode when the given polyline originates from a third-party source such as a recorded track, a different routing service, or user input.

  • update: Reconstruct the given route as close as possible to the provided route polyline, ignoring time-dependent driving and legal restrictions in order to keep the input polyline geometry stable. The input polyline is expected to be normalized, without any loops or gaps.


    Notice: The resulting reconstructed route tries to accurately follow the road network and might result in an illegal route due to potential violation of driving restrictions.

Note: In any of the modes, the algorithm might relax certain restrictions near the origin to offer a more sensible route instead of a no-route-found. This ensures that routes planned with our service can be reconstructed.


In short, this table summarizes the differences between the modes and restrictions:

Mode / Restrictiontrafficno-throughtime-dependent
normal✗✗✓
strict✓✓✓
track✓✓✓
update✓✗✗
Default value:normal
traffic
boolean

Possible values are:

  • true: Use 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 service takes road closures and road works into account 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 parameter can be specified multiple times (e.g., …&avoid=motorways&avoid=ferries&…).


Possible values are listed under Avoid parameter possible values.


Note: In calculateReachableRange requests, the value alreadyUsedRoads must not be used.

travelMode
string

The mode of travel for the requested route.

  • Note that the requested travelMode may not be available for the entire route.

  • If the requested travelMode is not available for a particular section, the travelMode field for that section in the response will be set to “other”.

Note that travel modes bus, motorcycle, taxi, and van are in BETA functionality.

  • Full restriction data is not available in all areas.

  • In calculateReachableRange requests, the values bicycle and pedestrian must not be used.

Default value:car
Other values:
  • truck
  • taxi
  • bus
  • van
  • motorcycle
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:
  • low
  • high
windingness
string

Level of turns for a thrilling route.


Note: This parameter can only be used in conjunction with routeType=thrilling.


Default value:normal
Other values:
  • low
  • high
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 Consumption model parameters 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 is 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):

  • B
  • C
  • D
  • E

Reference:

vehicleHasElectricTollCollectionTransponder
string

Specifies whether the route calculation should try to avoid ETC-transponder-only toll roads if the vehicle does not have an ETC transponder. Possible values are:

  • all: Do not avoid ETC-transponder-only toll roads.
  • none: Avoids ETC-transponder-only toll roads.
Default value:all

Consumption model parameters

The service provides a set of parameters for describing a vehicle-specific Consumption model in detail. These parameters must be specified in a calculateReachableRange request.

Depending on the value of vehicleEngineType, two principal Consumption models are supported:

  • 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.

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:

  1. 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.
  2. 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).
  3. 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).
  4. 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).
  5. If *Efficiency parameters are specified by the user, then vehicleWeight must also be specified.
    • When vehicleEngineType is combustion, fuelEnergyDensityInMJoulesPerLiter must be specified as well.
  6. If *Efficiency parameters are specified by the user, then consumptionInkWhPerkmAltitudeGain and recuperationInkWhPerkmAltitudeLoss cannot be specified.
  7. 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.

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

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.

  • Provided as an unordered list of speed/consumption rate pairs.

  • The list defines points on a consumption curve.

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 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.

  • This is the same parameter as documented in the Request parameters section.

  • It must be strictly positive when used in the context of the Consumption model.

  • Weight restrictions are considered.

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.01
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.01
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.01
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.01
Maximum value: 1/uphillEfficiency

The Electric consumption model

The Electric consumption model is used when vehicleEngineType is set to electric. The following data table describes all 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.

  • Provided as an unordered list of speed/consumption-rate pairs.

  • The list defines points on a consumption curve.

Consumption rates for speeds not in the list are found as follows:

  • By linear interpolation, if the given speed lies between two speeds in the list.

  • Otherwise, by linear extrapolation using a constant (ΔConsumption/ΔSpeed) derived from 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 required only if any *Efficiency parameter is set.

  • This is the same parameter as documented in the Request parameters section.

  • It must be strictly positive when used in the context of the Consumption model.

  • Weight restrictions are considered.

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 into 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.01
Maximum value: 1.0

decelerationEfficiency
float

Specifies the efficiency of converting kinetic energy into electric energy when the vehicle decelerates (i.e., ElectricEnergyGained/ KineticEnergyLost).
Notes:

  • It must be paired with accelerationEfficiency.

  • It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.01
Maximum value: 1/accelerationEfficiency

uphillEfficiency
float

Specifies the efficiency of converting electric energy into potential energy when the vehicle gains elevation (i.e., PotentialEnergyGained/ElectricEnergyConsumed).
Notes:

  • It must be paired with downhillEfficiency.

  • It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.01
Maximum value: 1.0

downhillEfficiency
float

Specifies the efficiency of converting potential energy to electric energy when the vehicle loses elevation (i.e, ElectricEnergyGained/PotentialEnergyLost).
Notes:

  • It must be paired with uphillEfficiency.

  • It cannot be used with consumptionInkWhPerkmAltitudeGain or recuperationInkWhPerkmAltitudeLoss.

Minimum value: 0.01
Maximum value: 1/uphillEfficiency

consumptionInkWhPerkmAltitudeGain
float

Specifies the amount of electric energy, in kWh, consumed by the vehicle when 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 amount of electric energy, in kWh, gained by the vehicle when 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

POST data parameters

The supportingPoints and encodedPolyline fields, which represent a polyline using different route geometry formats, are used to guarantee a higher degree of consistency between the reachable range polygon and the reachable part of a particular route.
For more information on representing route geometry formats, see the Route geometry representation formats section.

The route represented by the given polyline is reconstructed internally, using the same parameters as those used for the reachable range calculation. The reachable part of the route, which could be the entire route or a beginning section, is found by determining the farthest point the vehicle can reach on the route with its current budget. The reachable part of the route is not explicitly returned, but it is used internally to ensure it is contained in the resulting reachable area.

  • The first element of the given polyline must be identical to the origin point of the calculateReachableRange request.
  • If a polyline is provided, then it is mandatory to specify energyBudgetInkWh and a detailed Electric Consumption Model.
  • The route given by the polyline may contain traffic incidents of type ROAD_CLOSURE, which are ignored for the calculation of the reachable part of the route.
  • If a polyline is provided and the route reconstruction fails, the request fails with CANNOT_RESTORE_BASEROUTE in the detailedError field from the error response.
  • Road closures are ignored during the reconstruction of the given polyline (the reconstructed route may go through closures) but they are not ignored in the calculation of the reachable range.

The POST data should be in JSON format, see the Content-Type header. All POST data parameters are optional, but 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 (currently 10 MB); exceeding it results in a response with the response code 413.

The following table describes the parameters that can be used in the Calculate Reachable Range service.

ParameterDescription

supportingPoints
array of point objects

An array of point objects to be used as input for route reconstruction.
For more information on representing route geometry formats, see the Route geometry representation formats section.

encodedPolyline
string

A string in the encoded polyline format, representing the array of points to be used as input for route reconstruction.
The precision used to encode the polyline must be set in the encodedPolylinePrecision field.
For more information on representing route geometry formats, see the Route geometry representation formats section.

encodedPolylinePrecision
integer

The precision used to encode the polyline in the encodedPolyline field.
Must be 5 or 7.
Must be paired with encodedPolyline.

avoidVignette
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 all toll roads with vignettes are to be avoided.

  • Toll roads with vignettes in countries not in the array are unaffected.

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 that should be avoided 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.
  • A rectangle cannot cross the 180th meridian.
  • Each rectangle must lie 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.

Response data

Response headers

The following data table describes the HTTP response headers of particular interest to 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:

  • no-cache
  • no-transform
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 clients.
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 the HTTP response codes of particular interest to Calculate Reachable Range service clients.

Code

Meaning & possible causes

200

OK: A range was calculated and the body of the response contains the data for a successful response.

400

Bad request:

  • One or more parameters were incorrectly specified.
  • Some parameters are mutually exclusive.
  • The origin point is not near enough to a road.

  • A reachable range consistent with the given parameters could not be found.

403

Permission or authentication issues:

  • Forbidden
  • Not authorized
  • Account inactive
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 an HTTP method other than GET or POST.

408

Request timeout: The client took too long to transmit the request.

414

The request 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.

Example of a successful response

Response body
{
  "formatVersion": "0.0.1",
  "reachableRange": {
    "center": {
      "latitude": 50.9745,
      "longitude": 5.86605
    },
    "boundary": [
      {
        "latitude": 50.98532,
        "longitude": 5.86595
      },
      {
        "latitude": 50.98148,
        "longitude": 5.86371
      },
      {
        "latitude": 50.98382,
        "longitude": 5.86248
      },
      {
        "latitude": 50.97733,
        "longitude": 5.86437
      },
      {
        "latitude": 50.98242,
        "longitude": 5.85815
      },
      {
        "latitude": 50.9818,
        "longitude": 5.85436
      },
      {
        "latitude": 50.97964,
        "longitude": 5.85511
      },
      {
        "latitude": 50.97844,
        "longitude": 5.84836
      },
      {
        "latitude": 50.97732,
        "longitude": 5.84762
      },
      {
        "latitude": 50.9743,
        "longitude": 5.84969
      },
      {
        "latitude": 50.97,
        "longitude": 5.84589
      },
      {
        "latitude": 50.9668,
        "longitude": 5.85043
      },
      {
        "latitude": 50.96705,
        "longitude": 5.85374
      },
      {
        "latitude": 50.96914,
        "longitude": 5.86007
      },
      {
        "latitude": 50.96284,
        "longitude": 5.85818
      },
      {
        "latitude": 50.9658,
        "longitude": 5.86256
      },
      {
        "latitude": 50.96201,
        "longitude": 5.86273
      },
      {
        "latitude": 50.96405,
        "longitude": 5.86589
      },
      {
        "latitude": 50.97104,
        "longitude": 5.86665
      },
      {
        "latitude": 50.96513,
        "longitude": 5.86786
      },
      {
        "latitude": 50.96663,
        "longitude": 5.8692
      },
      {
        "latitude": 50.963,
        "longitude": 5.87398
      },
      {
        "latitude": 50.96437,
        "longitude": 5.87707
      },
      {
        "latitude": 50.96371,
        "longitude": 5.88459
      },
      {
        "latitude": 50.9671,
        "longitude": 5.88358
      },
      {
        "latitude": 50.97004,
        "longitude": 5.88901
      },
      {
        "latitude": 50.97098,
        "longitude": 5.89176
      },
      {
        "latitude": 50.97478,
        "longitude": 5.88689
      },
      {
        "latitude": 50.97874,
        "longitude": 5.88598
      },
      {
        "latitude": 50.98175,
        "longitude": 5.88432
      },
      {
        "latitude": 50.97871,
        "longitude": 5.873
      },
      {
        "latitude": 50.98047,
        "longitude": 5.87153
      },
      {
        "latitude": 50.97948,
        "longitude": 5.86984
      },
      {
        "latitude": 50.98555,
        "longitude": 5.87028
      },
      {
        "latitude": 50.98632,
        "longitude": 5.87009
      },
      {
        "latitude": 50.98709,
        "longitude": 5.86749
      }
    ]
  },
  "report": {
    "effectiveSettings": [
      {
        "key": "avoid",
        "value": "motorways"
      },
      "...further settings..."
    ]
  }
}

Example of an error response

If an error occurs, the response contains the description of the error.

  • Errors such as MAP_MATCHING_FAILURE are returned in the same way as in a calculateRoute response.
  • If a calculateReachableRange request cannot compute a polygon consistent with the input parameters, it will fail with NO_RANGE_FOUND.

Special behavior for content type jsonp

(JSON with Padding)

When the contentType=jsonp is used, the returned HTTP status code is always OK (200).

  • This ensures that the jsonp callback will be invoked on the client side regardless of the outcome of the request.
  • To provide the client with the actual status of the request, a field called statusCode is added to the response body.

Currently, the preceding statement is not true for certain types of errors described below.

Special behavior of certain types of errors (authentication errors, request quota related errors, etc.)

  • For those errors, the HTTP status code is returned as normal (400, 500, …) and the response content type is text/xml, regardless of the request content type.
  • For those errors, the content doesn’t follow the documented format for error responses.
  • Note: This imperfection should not cause problems during normal use of the API.

Structure of a successful response

JSON field

Description

formatVersion
string		The format version.
statusCode
number

The original HTTP status code, as listed in the response codes (only included for content type jsonp).

reachableRange
object

A polygon described using a center field and a boundary field.

center
point object		The center of the polygon.
boundary
array of point objects

The polygon boundary. Each object in the array describes a location on the boundary of the polygon.

report
object

A report describing the request. Contains effectiveSettings .

effectiveSettings
array of objects

Effective parameters or data used when calling the Calculate Reachable Range API. Each object contains the fields key and value, both of which are strings.

Structure of an error response

JSON field

Description

detailedError

object

This object provides a representation of the error message. It contains a code and a message field.

JSON field

Description
code

string

The (non-complete) list of error codes is:

Error code

Description
MAP_MATCHING_FAILURE

Origin input point could not be matched to the map because there is no known drivable section near this point.

NO_RANGE_FOUND

The request cannot compute a polygon consistent with the input parameters.

CANNOT_RESTORE_BASEROUTE

The route reconstruction using supportingPoints failed.

BAD_INPUT

Some input parameter combination was not valid.

COMPUTE_TIME_LIMIT_EXCEEDED

The request exceeded the internal compute time limit and was canceled.

message string

A human readable error message.

  • It is a freeform string which may be extended in the future, so it is recommended to only match substrings of the description.

  • The string always contains an error code.

Example of a description string:

Engine error while executing range request: MAP_MATCHING_FAILURE: Origin (54.3226, 3.11463)

Route geometry representation formats

Certain request fields that describe route geometry using a polyline support two alternative representation formats:

  • An array of points defined as raw decimal coordinates, such as the supportingPoints field in requests.
  • An encoded polyline string, such as the encodedPolyline field in requests.

Where documented, either of the two representations can be used. This is purely a representational choice and is independent of any other statements about route geometry. The field containing the array of points is used as a stand-in for the concern of route geometry. For brevity, any references and constraints related to the polyline are stated using the stand-in only.

Using encoded polylines can significantly reduce the data size of requests and responses.

Encoded polyline format

For efficient representation of polylines as encoded polyline strings, this service uses an extended version of the Encoded Polyline Algorithm Format.
The original algorithm limits coordinate precision to 5 decimal places by using a multiplier of 1e5 for the decimal values. The extension allows using multipliers of both 1e5 and 1e7. These multipliers correspond to precisions of 5 and 7 decimal places. Please note that each field in the encoded polyline format may have limitations on its supported precisions.
Since the encoded polyline string doesn’t contain information of the precision or multiplier used, this information must be provided separately alongside each encoded polyline string.
We recommend taking special care when using the higher precision, as some encoding implementations may suffer internal overflows with the higher multiplier.

Encoding

When encoding a polyline, select a supported precision and use the respective multiplier for the decimal value instead of the fixed 1e5 multiplier in the original algorithm (refer to the following table).
Otherwise, the encoding process remains the same as in the original algorithm. Ensure to send the precision used alongside each encoded polyline string in the request.

Decoding

When decoding a received polyline, use the provided precision next to the encoded polyline string to determine the appropriate multiplier for the decimal value instead of the fixed 1e5 multiplier in the original algorithm (refer to the following table). Otherwise, the decoding process remains the same as in the original algorithm. Note that each encoded polyline string is accompanied by the precision used for its encoding.

Precisions and multipliers

The following table illustrates the relationship between precision and multiplier:

Precision

Multiplier

51e5
71e7

Known Limitations

  • The polygon returned by the Calculate Reachable Range service provides an approximate representation of the area that can be reached within the specified budget, using routes matching the specified routeType and other specified parameters. The characteristics of the underlying algorithm affect the representation of the reachable area. This means that the polygon cannot precisely reflect all possible area contours, inevitably resulting in differences from the actual area.

  • In certain situations, the polygon may be smaller or larger than the actual reachable area.

    • Portions of the reachable area may be missing from the polygon, so a route planned with the same criteria could have sections which are reachable but lie outside of the polygon.
    • The polygon might include regions outside the truly reachable area.

  • Internal sanity checks are performed on the computed polygon. Due to the heuristic nature of these checks, the results may occasionally seem unexpected. For example, the check may detect that the size of the polygon is inconsistent with the request input, especially the specified budget. When this occurs, the request fails with NO_RANGE_FOUND, which is expected behavior.