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
    &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\
'{
   "supportingPoints":[
     {
       "latitude":52.5093,"longitude":13.42936
     },
     {
       "latitude":52.50844,"longitude":13.42859
     }
   ],
   "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.
  • 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.
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.
Optional parameters
Parameter Description
fuelBudgetInLiters
float
Fuel budget in liters that determines maximal range which can be travelled using the specified Combustion Consumption Model.
Note: Required if the vehicleEngineType is combustion and timeBudgetInSec is not used.
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 travelled using the specified Electric Consumption Model.
Note: Required if the vehicleEngineType is electric and timeBudgetInSec is not used.
Minimum value: 0
Maximum value: currentChargeInkWh (if specified)
timeBudgetInSec
float
The time budget in seconds that determines the maximal range which can be travelled using driving time. The consumption parameters will only affect eco-routes and thereby indirectly the driving time.
Note: Required if no other budget is used.
Value: 0

Explanation: Exactly one budget must be used in a calculateReachableRange Request.

  • Unless timeBudgetInSec is used as a budget, it is mandatory to specify a detailed Consumption Model that matches the value of vehicleEngineType.
  • Further parameters not contained in the preceding table can be specified, and 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">
    <copyright>Copyright 2018 TomTom International BV. All rights reserved. This navigation data is the proprietary copyright of TomTom International BV and may be used only in accordance with the terms of a fully executed license agreement entered into between TomTom International BV, or an authorised reseller and yourself. If you have not entered into such a license agreement you are not authorised to use this data in any manner and should immediately return it to TomTom International BV.
    </copyright>
    <privacy>TomTom keeps information that tells us how and when you use our services. This includes information about the device you are using and the information we receive while you use the service, such as locations, routes, destinations and search queries. TomTom is unable to identify you based on the information it collects, and will not try to. TomTom uses the information for technical diagnostics, to detect fraud and abuse, to create usage reports, and to improve its services. The information is kept only for these purposes and for a limited period of time, after which it is destroyed. TomTom applies security methods based on industry standards to protect the information against unauthorised access. TomTom will not give anyone else access to the information or use it for any other purpose, unless explicitly and lawfully ordered to do so following due legal process. You can find out more at http://tomtom.com/privacy. You can contact TomTom by going to http://tomtom.com/support.
    </privacy>
    <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",
    "copyright":"Copyright 2018 TomTom International BV. All rights reserved. This navigation data is the proprietary copyright of TomTom International BV and may be used only in accordance with the terms of a fully executed license agreement entered into between TomTom International BV, or an authorised reseller and yourself. If you have not entered into such a license agreement you are not authorised to use this data in any manner and should immediately return it to TomTom International BV.",
    "privacy":"TomTom keeps information that tells us how and when you use our services. This includes information about the device you are using and the information we receive while you use the service, such as locations, routes, destinations and search queries. TomTom is unable to identify you based on the information it collects, and will not try to. TomTom uses the information for technical diagnostics, to detect fraud and abuse, to create usage reports, and to improve its services. The information is kept only for these purposes and for a limited period of time, after which it is destroyed. TomTom applies security methods based on industry standards to protect the information against unauthorised access. TomTom will not give anyone else access to the information or use it for any other purpose, unless explicitly and lawfully ordered to do so following due legal process. You can find out more at http://tomtom.com/privacy. You can contact TomTom by going to http://tomtom.com/support.",
    "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">
    <copyright>Copyright 2018 TomTom International BV. All rights reserved. This navigation data is the proprietary copyright of TomTom International BV and may be used only in accordance with the terms of a fully executed license agreement entered into between TomTom International BV, or an authorised reseller and yourself. If you have not entered into such a license agreement you are not authorised to use this data in any manner and should immediately return it to TomTom International BV.</copyright>
    <privacy>TomTom keeps information that tells us how and when you use our services. This includes information about the device you are using and the information we receive while you use the service, such as locations, routes, destinations and search queries. TomTom is unable to identify you based on the information it collects, and will not try to. TomTom uses the information for technical diagnostics, to detect fraud and abuse, to create usage reports, and to improve its services. The information is kept only for these purposes and for a limited period of time, after which it is destroyed. TomTom applies security methods based on industry standards to protect the information against unauthorised access. TomTom will not give anyone else access to the information or use it for any other purpose, unless explicitly and lawfully ordered to do so following due legal process. You can find out more at http://tomtom.com/privacy. You can contact TomTom by going to http://tomtom.com/support.</privacy>
    <error description="Error description"/>
</calculateReachableRangeResponse>

The equivalent JSON error Response would look like this:

{
   "formatVersion":"0.0.1",
   "copyright":"Copyright 2018 TomTom International BV. All rights reserved. This navigation data is the proprietary copyright of TomTom International BV and may be used only in accordance with the terms of a fully executed license agreement entered into between TomTom International BV, or an authorised reseller and yourself. If you have not entered into such a license agreement you are not authorised to use this data in any manner and should immediately return it to TomTom International BV.",
   "privacy":"TomTom keeps information that tells us how and when you use our services. This includes information about the device you are using and the information we receive while you use the service, such as locations, routes, destinations and search queries. TomTom is unable to identify you based on the information it collects, and will not try to. TomTom uses the information for technical diagnostics, to detect fraud and abuse, to create usage reports, and to improve its services. The information is kept only for these purposes and for a limited period of time, after which it is destroyed. TomTom applies security methods based on industry standards to protect the information against unauthorised access. TomTom will not give anyone else access to the information or use it for any other purpose, unless explicitly and lawfully ordered to do so following due legal process. You can find out more at http://tomtom.com/privacy. You can contact TomTom by going to http://tomtom.com/support.",
   "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).