Calculate Reachable Range

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:

• Required parameters (Base path)
• Optional parameters

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

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

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

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

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.

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.

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

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

Structure of an error response

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