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

Calculate Reachable Range

 

Service version: 1.0
Last edit: 2019.02.07

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=*****
    &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
    &vehicleEngineType=vehicleEngineType
    &constantSpeedConsumptionInLitersPerHundredkm=CombustionConstantSpeedConsumptionPairs
    &currentFuelInLiters=float
    &auxiliaryPowerInLitersPerHour=float
    &fuelEnergyDensityInMJoulesPerLiter=float
    &accelerationEfficiency=float
    &decelerationEfficiency=float
    &uphillEfficiency=float
    &downhillEfficiency=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=*****

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=*****" -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=*****

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=*****"\
 -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 XML error Response would look like this:

<?xml version="1.0" encoding="utf-8"?>
<calculateReachableRangeResponse xmlns="http://api.tomtom.com/routing" formatVersion="0.0.1">
    <error description="Error description"/>
</calculateReachableRangeResponse>

The equivalent JSON error Response would look like this:

{
   "formatVersion":"0.0.1",
   "error":{
      "description":"Error description"
   }
}

Special behaviour for content type jsonp (JSON with padding)

When the contentType=jsonp, 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 (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.
  • 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

XML element field Description
<calculateReachableRangeResponse> The main XML Response element.
<error> Contains a description field with a human-readable error message.
<statusCode> The original HTTP status code as listed in Response Codes (included for content type jsonp only).

You are here