Calculate Reachable Range

Service version: 1
Last edit: 2022.08.10
TomTom Maps

Purpose

The Calculate Reachable Range service calculates a set of locations that can be reached from the origin point.

  • It optimizes routes with a given route-type (e.g., fastest, eco, etc.)
  • It limits the range for 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 respective parameters. For their details, please see the Common Routing Parameters page. For required and optional parameters, see the following sections:

get
Request example
1https://{baseURL}/routing/{versionNumber}/calculateReachableRange/{origin}/{contentType}?key={Your_API_Key}
2&callback={callback}
3&fuelBudgetInLiters={float}
4&energyBudgetInkWh={float}
5&timeBudgetInSec={float}
6&distanceBudgetInMeters={float}
7&report={effectiveSettings}
8&departAt={time}
9&routeType={routeType}
10&traffic={boolean}
11&avoid={avoidType}
12&prefer={preferType}
13&maxFerryLengthInMeters={float}
14&travelMode={travelMode}
15&hilliness={hilliness}
16&windingness={windingness}
17&vehicleMaxSpeed={vehicleMaxSpeed}
18&vehicleWeight={vehicleWeight}
19&vehicleAxleWeight={vehicleAxleWeight}
20&vehicleNumberOfAxles={vehicleNumberOfAxles}
21&vehicleLength={vehicleLength}
22&vehicleWidth={vehicleWidth}
23&vehicleHeight={vehicleHeight}
24&vehicleCommercial={boolean}
25&vehicleLoadType={vehicleLoadType}
26&vehicleAdrTunnelRestrictionCode={vehicleAdrTunnelRestrictionCode}
27&vehicleEngineType={vehicleEngineType}
28&handsFreeDrivingCapability={handsFreeDrivingCapability}
29&constantSpeedConsumptionInLitersPerHundredkm={CombustionConstantSpeedConsumptionPairs}
30&currentFuelInLiters={float}
31&auxiliaryPowerInLitersPerHour={float}
32&fuelEnergyDensityInMJoulesPerLiter={float}
33&accelerationEfficiency={float}
34&decelerationEfficiency={float}
35&uphillEfficiency={float}
36&downhillEfficiency={float}
37&consumptionInkWhPerkmAltitudeGain={float}
38&recuperationInkWhPerkmAltitudeLoss={float}
39&constantSpeedConsumptionInkWhPerHundredkm={ElectricConstantSpeedConsumptionPairs}
40&currentChargeInkWh={float}
41&maxChargeInkWh={float}
42&auxiliaryPowerInkW={float}

GET URL example

Note: Linebreaks are designated by "\".

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

POST URL example

Note: Linebreaks are designated by "\".

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

POST curl command examples

Note: Linebreaks are designated by "\".

post
POST curl command example
1curl -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}"\
2 -H "accept: */*" -H "Content-Type: application/json" -d\
3'{
4 "supportingPoints": [
5 {
6 "latitude": 52.50931,
7 "longitude": 13.42936
8 },
9 {
10 "latitude": 52.50872,
11 "longitude": 13.42900
12 },
13 {
14 "latitude": 52.50844,
15 "longitude": 13.42859
16 }
17 ],
18 "avoidVignette":[
19 "AUS","CHE"
20 ],
21 "avoidAreas":{
22 "rectangles":[
23 {
24 "southWestCorner":{
25 "latitude":48.81851,"longitude":2.26593
26 },
27 "northEastCorner":{
28 "latitude":48.90309,"longitude":2.41115
29 }
30 }
31 ]
32 }
33}'
post
POST curl command example with encoded polyline
1curl -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}"\
2 -H "accept: */*" -H "Content-Type: application/json" -d\
3'{
4 "encodedPolyline": "evn_Io|}pAtBfAv@pA",
5 "encodedPolylinePrecision": 5,
6 "avoidVignette":[
7 "AUS","CHE"
8 ],
9 "avoidAreas":{
10 "rectangles":[
11 {
12 "southWestCorner":{
13 "latitude":48.81851,"longitude":2.26593
14 },
15 "northEastCorner":{
16 "latitude":48.90309,"longitude":2.41115
17 }
18 }
19 ]
20 }
21}'

Types

There currently are no additional types specific to the Calculate Reachable Range service; the common types are listed on the Common Routing Parameters page.

Request headers

There currently are no additional headers specific to the Calculate Reachable Range service; the common headers are listed on the Common Routing Parameters page.

Base path parameters

The following table describes a subset of the parameters that can be used in the Calculate Reachable Range service; the remaining parameters are listed on the Common Routing Parameters page.

  • 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

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 Common Routing Parameters page for the format and possible values.

Request parameters

The following table describes a subset of the parameters that can be used in the Calculate Reachable Range service; the remaining parameters are listed on the Common Routing Parameters page.

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

Optional parameters

Description

fuelBudgetInLiters
float

Fuel budget in liters that determines maximal range which 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 maximal 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

Further parameters not contained in the preceding table can be specified. A complete list is located in the Common Routing Parameters page. This page also includes the parameters used to define a detailed Consumption Model.

POST data parameters

The supportingPoints field is used to guarantee a higher degree of consistency between the reachable-range polygon and the reachable part of a particular route.

The route represented by supportingPoints is reconstructed internally, using the same parameters as 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 go on the route on 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 supportingPoints must be identical to the origin point of the calculateReachableRange request.
  • If supportingPoints is used, 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 supportingPoints is used and the route reconstruction fails, the request will fail with CANNOT_RESTORE_BASEROUTE in the detailedError field from the error response.
  • Road closures are ignored during the reconstruction of supportingPoints (the reconstructed route may go through closures) but they are not ignored for the calculation of the reachable range.

The following table describes a subset of the parameters that can be used in the Calculate Reachable Range service; the remaining parameters are listed on the Common Routing Parameters page.

ParameterDescription

supportingPoints
array of point objects

An array of point objects, to be used as input for route reconstruction.
supportingPoints and encodedPolyline are alternative representation formats and cannot be used simultaneously. See the Route geometry representation formats section for further information.

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.
supportingPoints and encodedPolyline are alternative representation formats and cannot be used simultaneously. See the Route geometry representation formats section for further information.

encodedPolylinePrecision
integer

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

Response data

Response headers

There currently are no additional response headers specific to the Calculate Reachable Range service; the common response headers are listed on the Common Routing Parameters page.

Response codes

There currently are no additional response codes specific to the Calculate Reachable Range service; the common response codes are listed on the Common Routing Parameters page.

Example of a successful response

Response body
1{
2 "formatVersion": "0.0.1",
3 "reachableRange": {
4 "center": {
5 "latitude": 50.9745,
6 "longitude": 5.86605
7 },
8 "boundary": [
9 {
10 "latitude": 50.98532,
11 "longitude": 5.86595
12 },
13 {
14 "latitude": 50.98148,
15 "longitude": 5.86371
16 },
17 {
18 "latitude": 50.98382,
19 "longitude": 5.86248
20 },
21 {
22 "latitude": 50.97733,
23 "longitude": 5.86437
24 },
25 {
26 "latitude": 50.98242,
27 "longitude": 5.85815
28 },
29 {
30 "latitude": 50.9818,
31 "longitude": 5.85436
32 },
33 {
34 "latitude": 50.97964,
35 "longitude": 5.85511
36 },
37 {
38 "latitude": 50.97844,
39 "longitude": 5.84836
40 },
41 {
42 "latitude": 50.97732,
43 "longitude": 5.84762
44 },
45 {
46 "latitude": 50.9743,
47 "longitude": 5.84969
48 },
49 {
50 "latitude": 50.97,
51 "longitude": 5.84589
52 },
53 {
54 "latitude": 50.9668,
55 "longitude": 5.85043
56 },
57 {
58 "latitude": 50.96705,
59 "longitude": 5.85374
60 },
61 {
62 "latitude": 50.96914,
63 "longitude": 5.86007
64 },
65 {
66 "latitude": 50.96284,
67 "longitude": 5.85818
68 },
69 {
70 "latitude": 50.9658,
71 "longitude": 5.86256
72 },
73 {
74 "latitude": 50.96201,
75 "longitude": 5.86273
76 },
77 {
78 "latitude": 50.96405,
79 "longitude": 5.86589
80 },
81 {
82 "latitude": 50.97104,
83 "longitude": 5.86665
84 },
85 {
86 "latitude": 50.96513,
87 "longitude": 5.86786
88 },
89 {
90 "latitude": 50.96663,
91 "longitude": 5.8692
92 },
93 {
94 "latitude": 50.963,
95 "longitude": 5.87398
96 },
97 {
98 "latitude": 50.96437,
99 "longitude": 5.87707
100 },
101 {
102 "latitude": 50.96371,
103 "longitude": 5.88459
104 },
105 {
106 "latitude": 50.9671,
107 "longitude": 5.88358
108 },
109 {
110 "latitude": 50.97004,
111 "longitude": 5.88901
112 },
113 {
114 "latitude": 50.97098,
115 "longitude": 5.89176
116 },
117 {
118 "latitude": 50.97478,
119 "longitude": 5.88689
120 },
121 {
122 "latitude": 50.97874,
123 "longitude": 5.88598
124 },
125 {
126 "latitude": 50.98175,
127 "longitude": 5.88432
128 },
129 {
130 "latitude": 50.97871,
131 "longitude": 5.873
132 },
133 {
134 "latitude": 50.98047,
135 "longitude": 5.87153
136 },
137 {
138 "latitude": 50.97948,
139 "longitude": 5.86984
140 },
141 {
142 "latitude": 50.98555,
143 "longitude": 5.87028
144 },
145 {
146 "latitude": 50.98632,
147 "longitude": 5.87009
148 },
149 {
150 "latitude": 50.98709,
151 "longitude": 5.86749
152 }
153 ]
154 },
155 "report": {
156 "effectiveSettings": [
157 {
158 "key": "avoid",
159 "value": "motorways"
160 },
161 "...further settings..."
162 ]
163 }
164}

Example of an error response

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

The format follows the exact same format as for Calculate Route.

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

  • For those errors the HTTP status code is returned as normal (400, 500, ...) and the response content type is text/xml independent from 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 response codes (only included for content type jsonp).

reachableRange
object

A polygon described by means of 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, containing strings.

Structure of an error response

The structure follows the exact same format as for Calculate Route.