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

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 examples

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

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.

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

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

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.