Calculate Reachable Range

Service version: 1
Last edit: 2022.08.10

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&maxFerryLengthInMeters={float}
13&travelMode={travelMode}
14&hilliness={hilliness}
15&windingness={windingness}
16&vehicleMaxSpeed={vehicleMaxSpeed}
17&vehicleWeight={vehicleWeight}
18&vehicleAxleWeight={vehicleAxleWeight}
19&vehicleLength={vehicleLength}
20&vehicleWidth={vehicleWidth}
21&vehicleHeight={vehicleHeight}
22&vehicleCommercial={boolean}
23&vehicleLoadType={vehicleLoadType}
24&vehicleAdrTunnelRestrictionCode={vehicleAdrTunnelRestrictionCode}
25&vehicleEngineType={vehicleEngineType}
26&constantSpeedConsumptionInLitersPerHundredkm={CombustionConstantSpeedConsumptionPairs}
27&currentFuelInLiters={float}
28&auxiliaryPowerInLitersPerHour={float}
29&fuelEnergyDensityInMJoulesPerLiter={float}
30&accelerationEfficiency={float}
31&decelerationEfficiency={float}
32&uphillEfficiency={float}
33&downhillEfficiency={float}
34&consumptionInkWhPerkmAltitudeGain={float}
35&recuperationInkWhPerkmAltitudeLoss={float}
36&constantSpeedConsumptionInkWhPerHundredkm={ElectricConstantSpeedConsumptionPairs}
37&currentChargeInkWh={float}
38&maxChargeInkWh={float}
39&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 example

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}'

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 pathDescription
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 parametersDescription
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 remaining parameters are listed on the Common Routing Parameters page.

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

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.

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.

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