Sorry, you need to enable JavaScript to visit this website.

Calculate Reachable Range

 

Service version: 1.0
Last edit: 2021.04.29

Deprecation Notice:

Dec 1, 2020:
  • All XML capabilities of the Routing API are deprecated. This includes
    • base path parameter contentType value xml
    • request header Content-Type value application/xml
  • These capabilities will be withdrawn following a 12 month deprecation period.
  • The planned withdrawal date is Dec 1, 2021.
  • Following withdrawal, requests using this functionality may receive an HTTP error in the response.
  • During the deprecation period the usage of any XML related functionality may result in an additional Warning: 299 - "XML is deprecated" response header.

On this page

Purpose

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

  1. It optimizes routes with a given route-type (e.g., fastest, eco, etc.)
  2. 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.

  1. Go to the TomTom API Explorer page.
  2. Click an endpoint.
    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  3. Review the response.

Request data

HTTPS method: GETPOST

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 ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.
https://baseURL/routing/versionNumber/calculateReachableRange/origin/contentType?key=Your_API_Key
    &callback=callback
    &fuelBudgetInLiters=float
    &energyBudgetInkWh=float
    &timeBudgetInSec=float
    &distanceBudgetInMeters=float
    &report=effectiveSettings
    &departAt=time
    &routeType=routeType
    &traffic=boolean
    &avoid=avoidType
    &travelMode=travelMode
    &hilliness=hilliness
    &windingness=windingness
    &vehicleMaxSpeed=vehicleMaxSpeed
    &vehicleWeight=vehicleWeight
    &vehicleAxleWeight=vehicleAxleWeight
    &vehicleLength=vehicleLength
    &vehicleWidth=vehicleWidth
    &vehicleHeight=vehicleHeight
    &vehicleCommercial=boolean
    &vehicleLoadType=vehicleLoadType
    &vehicleAdrTunnelRestrictionCode=vehicleAdrTunnelRestrictionCode
    &vehicleEngineType=vehicleEngineType
    &constantSpeedConsumptionInLitersPerHundredkm=CombustionConstantSpeedConsumptionPairs
    &currentFuelInLiters=float
    &auxiliaryPowerInLitersPerHour=float
    &fuelEnergyDensityInMJoulesPerLiter=float
    &accelerationEfficiency=float
    &decelerationEfficiency=float
    &uphillEfficiency=float
    &downhillEfficiency=float
    &consumptionInkWhPerkmAltitudeGain=float
    &recuperationInkWhPerkmAltitudeLoss=float
    &constantSpeedConsumptionInkWhPerHundredkm=ElectricConstantSpeedConsumptionPairs
    &currentChargeInkWh=float
    &maxChargeInkWh=float
    &auxiliaryPowerInkW=float

GET URL example

Note: Linebreaks are designated by "\".

https://api.tomtom.com/routing/1/calculateReachableRange/52.50931,13.42936/json?\
fuelBudgetInLiters=50&report=effectiveSettings\
&routeType=eco&traffic=true&avoid=unpavedRoads&travelMode=car&vehicleMaxSpeed=120\
&vehicleCommercial=false&vehicleEngineType=combustion\
&constantSpeedConsumptionInkWhPerHundredkm=50%2C8.2%3A130%2C21.3&key=Your_API_Key

GET curl command

Note: Linebreaks are designated by "\".

curl -X GET "https://api.tomtom.com/routing/1/calculateReachableRange/52.50931,13.42936/json?\
energyBudgetInkWh=50&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" -H "accept: */*"

POST URL example

Note: Linebreaks are designated by "\".

https://api.tomtom.com/routing/1/calculateReachableRange/52.50931,13.42936/json?\
energyBudgetInkWh=50&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

POST curl command

Note: Linebreaks are designated by "\".

curl -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"\
 -H "accept: */*" -H "Content-Type: application/json" -d\
'{
   "avoidVignette":[
     "AUS","CHE"
   ],
   "avoidAreas":{
     "rectangles":[
       {
         "southWestCorner":{
           "latitude":48.81851,"longitude":2.26593
         },
         "northEastCorner":{
           "latitude":48.90309,"longitude":2.41115
         }
       }
    ]
  }
}'

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.

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
Parameter Description
versionNumber
integer
The service version number.
Value: The current value is 1.
origin
float
Point from which the range calculation should start.
Value: A latitude, longitude pair.

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.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
  • 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
Parameter 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)
  • 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: currentChargeInkWh (if 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
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

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

A successful response in XML may look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <calculateReachableRangeResponse formatVersion="0.0.1">
    <reachableRange>
        <center latitude="50.97450" longitude="5.86605"/>
        <boundary>
            <point latitude="50.98532" longitude="5.86595"/>
            <point latitude="50.98148" longitude="5.86371"/>
            <point latitude="50.98382" longitude="5.86248"/>
            <point latitude="50.97733" longitude="5.86437"/>
            <point latitude="50.98242" longitude="5.85815"/>
            <point latitude="50.98180" longitude="5.85436"/>
            <point latitude="50.97964" longitude="5.85511"/>
            <point latitude="50.97844" longitude="5.84836"/>
            <point latitude="50.97732" longitude="5.84762"/>
            <point latitude="50.97430" longitude="5.84969"/>
            <point latitude="50.97000" longitude="5.84589"/>
            <point latitude="50.96680" longitude="5.85043"/>
            <point latitude="50.96705" longitude="5.85374"/>
            <point latitude="50.96914" longitude="5.86007"/>
            <point latitude="50.96284" longitude="5.85818"/>
            <point latitude="50.96580" longitude="5.86256"/>
            <point latitude="50.96201" longitude="5.86273"/>
            <point latitude="50.96405" longitude="5.86589"/>
            <point latitude="50.97104" longitude="5.86665"/>
            <point latitude="50.96513" longitude="5.86786"/>
            <point latitude="50.96663" longitude="5.86920"/>
            <point latitude="50.96300" longitude="5.87398"/>
            <point latitude="50.96437" longitude="5.87707"/>
            <point latitude="50.96371" longitude="5.88459"/>
            <point latitude="50.96710" longitude="5.88358"/>
            <point latitude="50.97004" longitude="5.88901"/>
            <point latitude="50.97098" longitude="5.89176"/>
            <point latitude="50.97478" longitude="5.88689"/>
            <point latitude="50.97874" longitude="5.88598"/>
            <point latitude="50.98175" longitude="5.88432"/>
            <point latitude="50.97871" longitude="5.87300"/>
            <point latitude="50.98047" longitude="5.87153"/>
            <point latitude="50.97948" longitude="5.86984"/>
            <point latitude="50.98555" longitude="5.87028"/>
            <point latitude="50.98632" longitude="5.87009"/>
            <point latitude="50.98709" longitude="5.86749"/>
        </boundary>
    </reachableRange>
    <report>
        <effectiveSettings>
            <setting key="avoid" value="motorways"/>
  ...further settings...
        </effectiveSettings>
    </report>
</calculateReachableRangeResponse>

A successful response in JSON may look like this:

{
    "formatVersion":"0.0.1",
    "reachableRange":
        {
            "center":
                {"latitude":50.97450,"longitude":5.86605},
            "boundary": [
                {"latitude":50.98532,"longitude":5.86595},
                {"latitude":50.98148,"longitude":5.86371},
                {"latitude":50.98382,"longitude":5.86248},
                {"latitude":50.97733,"longitude":5.86437},
                {"latitude":50.98242,"longitude":5.85815},
                {"latitude":50.98180,"longitude":5.85436},
                {"latitude":50.97964,"longitude":5.85511},
                {"latitude":50.97844,"longitude":5.84836},
                {"latitude":50.97732,"longitude":5.84762},
                {"latitude":50.97430,"longitude":5.84969},
                {"latitude":50.97000,"longitude":5.84589},
                {"latitude":50.96680,"longitude":5.85043},
                {"latitude":50.96705,"longitude":5.85374},
                {"latitude":50.96914,"longitude":5.86007},
                {"latitude":50.96284,"longitude":5.85818},
                {"latitude":50.96580,"longitude":5.86256},
                {"latitude":50.96201,"longitude":5.86273},
                {"latitude":50.96405,"longitude":5.86589},
                {"latitude":50.97104,"longitude":5.86665},
                {"latitude":50.96513,"longitude":5.86786},
                {"latitude":50.96663,"longitude":5.86920},
                {"latitude":50.96300,"longitude":5.87398},
                {"latitude":50.96437,"longitude":5.87707},
                {"latitude":50.96371,"longitude":5.88459},
                {"latitude":50.96710,"longitude":5.88358},
                {"latitude":50.97004,"longitude":5.88901},
                {"latitude":50.97098,"longitude":5.89176},
                {"latitude":50.97478,"longitude":5.88689},
                {"latitude":50.97874,"longitude":5.88598},
                {"latitude":50.98175,"longitude":5.88432},
                {"latitude":50.97871,"longitude":5.87300},
                {"latitude":50.98047,"longitude":5.87153},
                {"latitude":50.97948,"longitude":5.86984},
                {"latitude":50.98555,"longitude":5.87028},
                {"latitude":50.98632,"longitude":5.87009},
                {"latitude":50.98709,"longitude":5.86749}
                ]
        },
    "report":
        {
            "effectiveSettings": [
                {"key": "avoid","value": "motorways"},
  ...further settings...
                ]
        }
}

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, with the only difference, that the root node is called calculateReachableRangeResponse for XML.

Special behaviour 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

XML element field Description
<calculateReachableRangeResponse> The main XML response element.
<reachableRange> A description of a polygon comprised of boundary points and a center point.
<center> A description of the center point.
<boundary> A description of the polygon boundary, comprised of a list of points.
<point> A location on the surface of the globe defined as a latitude longitude pair.
<effectiveSettings> Effective parameters or data used when calling the Calculate Reachable Range API.
<statusCode> The original HTTP status code as listed in response codes (included for content type jsonp only).

Structure of an error response

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