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:
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¤tFuelInLiters={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¤tChargeInkWh={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
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
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 "avoidVignette":[5 "AUS","CHE"6 ],7 "avoidAreas":{8 "rectangles":[9 {10 "southWestCorner":{11 "latitude":48.81851,"longitude":2.2659312 },13 "northEastCorner":{14 "latitude":48.90309,"longitude":2.4111515 }16 }17 ]18 }19}'
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
, ordistanceBudgetInMeters
) must be used. - When
fuelBudgetInLiters
orenergyBudgetInkWh
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: currentFuelInLiters (if specified)
|
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: currentChargeInkWh (if specified)
|
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 |
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 |
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
There currently are no additional parameters specific to the Calculate Reachable Range service; the common 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.866059 },10 "boundary":11 [12 {13 "latitude": 50.98532,14 "longitude": 5.8659515 },16 {17 "latitude": 50.98148,18 "longitude": 5.8637119 },20 {21 "latitude": 50.98382,22 "longitude": 5.8624823 },24 {25 "latitude": 50.97733,26 "longitude": 5.8643727 },28 {29 "latitude": 50.98242,30 "longitude": 5.8581531 },32 {33 "latitude": 50.9818,34 "longitude": 5.8543635 },36 {37 "latitude": 50.97964,38 "longitude": 5.8551139 },40 {41 "latitude": 50.97844,42 "longitude": 5.8483643 },44 {45 "latitude": 50.97732,46 "longitude": 5.8476247 },48 {49 "latitude": 50.9743,50 "longitude": 5.8496951 },52 {53 "latitude": 50.97,54 "longitude": 5.8458955 },56 {57 "latitude": 50.9668,58 "longitude": 5.8504359 },60 {61 "latitude": 50.96705,62 "longitude": 5.8537463 },64 {65 "latitude": 50.96914,66 "longitude": 5.8600767 },68 {69 "latitude": 50.96284,70 "longitude": 5.8581871 },72 {73 "latitude": 50.9658,74 "longitude": 5.8625675 },76 {77 "latitude": 50.96201,78 "longitude": 5.8627379 },80 {81 "latitude": 50.96405,82 "longitude": 5.8658983 },84 {85 "latitude": 50.97104,86 "longitude": 5.8666587 },88 {89 "latitude": 50.96513,90 "longitude": 5.8678691 },92 {93 "latitude": 50.96663,94 "longitude": 5.869295 },96 {97 "latitude": 50.963,98 "longitude": 5.8739899 },100 {101 "latitude": 50.96437,102 "longitude": 5.87707103 },104 {105 "latitude": 50.96371,106 "longitude": 5.88459107 },108 {109 "latitude": 50.9671,110 "longitude": 5.88358111 },112 {113 "latitude": 50.97004,114 "longitude": 5.88901115 },116 {117 "latitude": 50.97098,118 "longitude": 5.89176119 },120 {121 "latitude": 50.97478,122 "longitude": 5.88689123 },124 {125 "latitude": 50.97874,126 "longitude": 5.88598127 },128 {129 "latitude": 50.98175,130 "longitude": 5.88432131 },132 {133 "latitude": 50.97871,134 "longitude": 5.873135 },136 {137 "latitude": 50.98047,138 "longitude": 5.87153139 },140 {141 "latitude": 50.97948,142 "longitude": 5.86984143 },144 {145 "latitude": 50.98555,146 "longitude": 5.87028147 },148 {149 "latitude": 50.98632,150 "longitude": 5.87009151 },152 {153 "latitude": 50.98709,154 "longitude": 5.86749155 }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 istext/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.