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

Calculate Reachable Range

The Calculate Reachable Range service calculates a set of locations that can be reached from the origin point. It optimizes for routes with a given route-type (e.g. fastest, eco, etc) but limits the range for the given budget and consumption parameters.

The information returned is a polygon boundary in counterclockwise orientation and the precise polygon center (the result of map-matching the origin point).

Types

There are currently no additional types specific to the Calculate Reachable Range service; the common types are listed on this page.

Request

Format

https://<baseURL>/routing/<versionNumber>/calculateReachableRange/<origin>[/<contentType>]?
    key=<apiKey>
    [&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>]

Example

https://api.tomtom.com/routing/1/calculateReachableRange/50.97452,5.86605?key=<APIKEY>&fuelBudgetInLiters=20&constantSpeedConsumptionInLitersPerHundredkm=50,6

Headers

There are currently no additional headers specific to the Calculate Reachable Range service; the common headers are listed on this page.

Base Path Parameters

The table below describes a subset of the parameters that can be used in the Calculate Reachable Range service; the remaining parameters are listed on this page. Required parameters must be used, or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.

Parameter Description Req'd? Type / Values Default Value
versionNumber Service version number. The current value is 1. Yes 1
origin Point from which the range calculation should start. Yes point

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 this page. Required parameters must be used, or the call will fail. Optional parameters, which are highlighted with [square brackets], may be used. 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.

Parameter Description Req'd? Type / Values Default Value Min Value Max Value
[fuelBudgetInLiters] Fuel budget in liters that determines maximal range which can be travelled using the specified Combustion Consumption Model. No, unless vehicleEngineType is combustion and timeBudgetInSec is not used float 0 currentFuelInLiters (if specified)
[energyBudgetInkWh] Electric energy budget in kilowatt hours (kWh) that determines maximal range which can be travelled using the specified Electric Consumption Model. No, unless vehicleEngineType is electric and timeBudgetInSec is not used float 0 currentChargeInkWh (if specified)
[timeBudgetInSec] Time budget in seconds that determines maximal range which can be travelled using driving time. The consumption parameters will only affect eco-routes and thereby indirectly the driving time. No, unless no other budget is used float 0

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 table above can be specified. Refer to this page for a complete list, including the parameters used to define a detailed Consumption Model.

POST Data Parameters

There are currently no additional parameters specific to the Calculate Reachable Range service; the common parameters are listed on this page.

Response

Response Headers

There are currently no additional response headers specific to the Calculate Reachable Range service; the common response headers are listed on this page.

Response Codes

There are currently no additional response codes specific to the Calculate Reachable Range service; the common response codes are listed on this page.

Example of a successful response

An XML response could 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 JSON response could 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

When 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 above 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. This imperfection should not cause problems during normal use of the API.

Structure of a successful response

Field Description
<calculateReachableRangeResponse> Main 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> Original HTTP status code as listed in Response Codes (included for content type jsonp only).

Structure of an error response

Field Description
<calculateReachableRangeResponse> Main response element.
<error> Contains a description field with a human readable error message.
<statusCode> Original HTTP status code as listed in Response Codes (included for content type jsonp only).