The Calculate Route service calculates a route between an origin and a destination, passing through waypoints if they are specified. The route will take into account factors such as current traffic and the typical road speeds on the requested day of the week and time of day.

Information returned includes the distance, estimated travel time, and a representation of the route geometry. Additional routing information such as optimized waypoint order or turn by turn instructions is also available, depending on the options selected.

Types

The table below describes a subset of the types that can be used in the Calculate Route service; the remaining types are listed on this page.

Request

Format

https://<baseURL>/routing/<versionNumber>/calculateRoute/<locations>[/<contentType>]?
    key=<apiKey>
    [&callback=<callback>]
    [&maxAlternatives=<alternativeRoutes>]
    [&alternativeType=<alternativeType>]
    [&minDeviationDistance=<integer>]
    [&minDeviationTime=<integer>]
    [&instructionsType=<instructionsType>]
    [&language=<language>]
    [&computeBestOrder=<boolean>]
    [&routeRepresentation=<routeRepresentation>]
    [&computeTravelTimeFor=<trafficTypes>]
    [&vehicleHeading=<integer>]
    [&sectionType=<sectionType>]
    [&report=effectiveSettings]
    [&departAt=<time>]
    [&arriveAt=<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/calculateRoute/52.50931,13.42936:52.50274,13.43872?key=<APIKEY>

Headers

There are currently no additional headers specific to the Calculate Route 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 Route 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.

Request Parameters

The table below describes a subset of the parameters that can be used in the Calculate Route 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.

As mentioned before, further parameters not contained in the table above can be specified. Some of them are used to define a detailed vehicle consumption model. Refer to this page for full documentation.

Using the detailed consumption model has two consequences for a calculateRoute request:

• When parameter routeType is set to eco, then the Consumption Model will be taken into account for route planning.
• When constantSpeedConsumption* is specified, the response will include either fuelConsumptionInLiters or batteryConsumptionInkWh (for vehicleEngineType set to combustion or electric, respectively) as an additional field in each summary element.

POST Data Parameters

<supportingPoints> is used for reconstructing a route and for calculating zero or more alternative routes to this reference route. The provided sequence of supporting points is used as input for route reconstruction. The alternative routes are calculated between the origin and destination points specified in the base path parameter locations. If both minDeviationDistance and minDeviationTime are set to zero, then these origin and destination points are expected to be at (or very near) the beginning and end of the reference route, respectively. Intermediate locations (waypoints) are not supported when using <supportingPoints>.

The reference route may contain traffic incidents of type ROAD_CLOSURE, which are ignored for its travel time and traffic delay calculation.

Setting at least one of minDeviationDistance or minDeviationTime to a value greater than zero has the following consequences:

• The origin point of the calculateRoute request must be on (or very near) the input reference route. If this is not the case, an error is returned. However, the origin point does not need to be at the beginning of the input reference route (it can be thought of as the current vehicle position on the reference route).
• The reference route, returned as the first route in the calculateRoute response, will start at the origin point specified in the calculateRoute request. The initial part of the input reference route up until the origin point will be excluded from the response.
• The values of minDeviationDistance and minDeviationTime determine how far alternative routes will be guaranteed to follow the reference route from the origin point onwards.
• The route must use departAt.
• The vehicleHeading is ignored.

The table below describes a subset of the parameters that can be used in the Calculate Route service; the remaining parameters are listed on this page.

XML request content example

<postData>
  <supportingPoints>
    <supportingPoint latitude="52.50930" longitude="13.42936"/>
    <supportingPoint latitude="52.50844" longitude="13.42859"/>
  </supportingPoints>
  <avoidVignette>
    AUS,CHE
  </avoidVignette>
</postData>

The <postData> element may be omitted if only supportingPoints are specified, so the following example continues to be supported for backward compatibility:

<supportingPoints>
  <supportingPoint latitude="52.50930" longitude="13.42936"/>
  <supportingPoint latitude="52.50844" longitude="13.42859"/>
</supportingPoints>

JSON request content example

{
  "supportingPoints": [
    {"latitude": 52.50930, "longitude": 13.42936},
    {"latitude": 52.50844, "longitude": 13.42859}
  ],
  "avoidVignette": [
    "AUS",
    "CHE"
  ]
}

Response

Response Headers

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

Response Codes

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

Example of a successful response

The routes in a successful response are listed in order of decreasing optimality. In case the request includes supporting points <supportingPoint>, the response will specify the reconstructed route before any alternative routes.

In the XML and JSON examples that follow, note that the fields <deviationDistance>, <deviationTime> and <deviationPoint> cannot occur if there is more than one leg because waypoints and supporting points are mutually exclusive.

An XML response could look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<calculateRouteResponse xmlns="http://api.tomtom.com/routing" formatVersion="0.0.12">
  <copyright>Copyright 2019 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>
  <route>
    <summary>
      <lengthInMeters>1147</lengthInMeters>
      <travelTimeInSeconds>157</travelTimeInSeconds>
      <trafficDelayInSeconds>0</trafficDelayInSeconds>
      <departureTime>2015-04-02T14:58:40+02:00</departureTime>
      <arrivalTime>2015-04-02T15:01:17+02:00</arrivalTime>
      <noTrafficTravelTimeInSeconds>120</noTrafficTravelTimeInSeconds>
      <historicTrafficTravelTimeInSeconds>157</historicTrafficTravelTimeInSeconds>
      <liveTrafficIncidentsTravelTimeInSeconds>161</liveTrafficIncidentsTravelTimeInSeconds>
      <fuelConsumptionInLiters>0.0155</fuelConsumptionInLiters>
      <deviationDistance>1735</deviationDistance>
      <deviationTime>127</deviationTime>
      <deviationPoint latitude="52.50904" longitude="13.42912"/>
    </summary>
    <leg>
      <summary>
        <lengthInMeters>108</lengthInMeters>
        <travelTimeInSeconds>11</travelTimeInSeconds>
        <trafficDelayInSeconds>0</trafficDelayInSeconds>
        <departureTime>2015-04-02T14:58:40+02:00</departureTime>
        <arrivalTime>2015-04-02T14:58:50+02:00</arrivalTime>
        <noTrafficTravelTimeInSeconds>10</noTrafficTravelTimeInSeconds>
        <historicTrafficTravelTimeInSeconds>11</historicTrafficTravelTimeInSeconds>
        <liveTrafficIncidentsTravelTimeInSeconds>13</liveTrafficIncidentsTravelTimeInSeconds>
        <fuelConsumptionInLiters>0.01</fuelConsumptionInLiters>
      </summary>
      <points>
        <point latitude="52.50931" longitude="13.42937"/>
        <point latitude="52.50904" longitude="13.42912"/>
        [...further points...]
      </points>
    </leg>
    [...further legs...]
    <sections>
      <section>
        <startPointIndex>0</startPointIndex>
        <endPointIndex>3</endPointIndex>
        <sectionType>TRAVEL_MODE</sectionType>
        <travelMode>other</travelMode>
      </section>
      <section>
        <startPointIndex>3</startPointIndex>
        <endPointIndex>7</endPointIndex>
        <sectionType>TRAVEL_MODE</sectionType>
        <travelMode>car</travelMode>
      </section>
      <section>
        <startPointIndex>2</startPointIndex>
        <endPointIndex>5</endPointIndex>
        <sectionType>TOLL_ROAD</sectionType>
      </section>
      <section>
        <startPointIndex>3</startPointIndex>
        <endPointIndex>4</endPointIndex>
        <sectionType>TUNNEL</sectionType>
      </section>
      <section>
        <startPointIndex>0</startPointIndex>
        <endPointIndex>1</endPointIndex>
        <sectionType>PEDESTRIAN</sectionType>
      </section>
      <section>
        <startPointIndex>3</startPointIndex>
        <endPointIndex>4</endPointIndex>
        <sectionType>TRAFFIC</sectionType>
        <simpleCategory>JAM</simpleCategory>
        <effectiveSpeedInKmh>40</effectiveSpeedInKmh>
        <delayInSeconds>158</delayInSeconds>
        <magnitudeOfDelay>1</magnitudeOfDelay>
        <tec>
          <effectCode>4</effectCode>
          <causes>
            <cause>
              <mainCauseCode>1</mainCauseCode>
            </cause>
            <cause>
              <mainCauseCode>26</mainCauseCode>
              <subCauseCode>2</subCauseCode>
            </cause>
          </causes>
        </tec>
      </section>
      [...further sections...]
    </sections>
    <guidance>
      <instructions>
        <instruction>
          <routeOffsetInMeters>0</routeOffsetInMeters>
          <travelTimeInSeconds>0</travelTimeInSeconds>
          <point latitude="52.50931" longitude="13.42937"/>
          <instructionType>LOCATION_DEPARTURE</instructionType>
          <street>An der Schillingbrücke</street>
          <countryCode>DEU</countryCode>
          <possibleCombineWithNext>false</possibleCombineWithNext>
          <drivingSide>RIGHT</drivingSide>
          <maneuver>DEPART</maneuver>
          <message>Leave from An der Schillingbrücke</message>
        </instruction>
        [...further instructions...]
      </instructions>
      <instructionGroups>
          <instructionGroup firstInstructionIndex="0" lastInstructionIndex="5">
          <groupLengthInMeters>4567</groupLengthInMeters>
          <groupMessage>Leave from An der Schillingbrücke and continue to A1/E35</groupMessage>
        </instructionGroup>
        [...further instruction groups...]
      </instructionGroups>
    </guidance>
  </route>
  [...further routes...]
  <optimizedWaypoints>
    <waypoint providedIndex="0" optimizedIndex="1"/>
    <waypoint providedIndex="1" optimizedIndex="0"/>
    [...further optimized waypoints...]
  </optimizedWaypoints>
  <report>
    <effectiveSettings>
      <setting key="avoid" value="motorways"/>
      <setting key="computeBestOrder" value="true"/>
      [...further settings...]
    </effectiveSettings>
  </report>
</calculateRouteResponse>

A JSON response could look like this:

{
  "formatVersion": "0.0.12",
  "copyright": "Copyright 2019 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.",
  "routes": [
    {
      "summary": {
        "lengthInMeters": 1147,
        "travelTimeInSeconds": 157,
        "trafficDelayInSeconds": 0,
        "departureTime": "2015-04-02T15:01:57+02:00",
        "arrivalTime": "2015-04-02T15:04:34+02:00",
        "noTrafficTravelTimeInSeconds": 120,
        "historicTrafficTravelTimeInSeconds": 157,
        "liveTrafficIncidentsTravelTimeInSeconds": 161,
        "fuelConsumptionInLiters": 0.0155,
        "deviationDistance": 1735,
        "deviationTime": 127,
        "deviationPoint": {
          "latitude": 52.50904,
          "longitude": 13.42912
        }
      },
      "legs": [
        {
          "summary": {
            "lengthInMeters": 108,
            "travelTimeInSeconds": 11,
            "trafficDelayInSeconds": 0,
            "departureTime": "2015-04-02T15:01:57+02:00",
            "arrivalTime": "2015-04-02T15:02:07+02:00",
            "noTrafficTravelTimeInSeconds": 10,
            "historicTrafficTravelTimeInSeconds": 11,
            "liveTrafficIncidentsTravelTimeInSeconds": 13,
            "fuelConsumptionInLiters": 0.01
          },
          "points": [
            {
              "latitude": 52.50931,
              "longitude": 13.42937
            },
            {
              "latitude": 52.50904,
              "longitude": 13.42912
            },
            [...further points...]
          ]
        },
        [...further legs...]
      ],
      "sections": [
        {
          "startPointIndex": 0,
          "endPointIndex": 3,
          "sectionType": "TRAVEL_MODE"
          "travelMode": "other"
        },
        {
          "startPointIndex": 3,
          "endPointIndex": 7,
          "sectionType": "TRAVEL_MODE"
          "travelMode": "car"
        },
        {
          "startPointIndex": 2,
          "endPointIndex": 5,
          "sectionType": "TOLL_ROAD"
        },
        {
          "startPointIndex": 3,
          "endPointIndex": 4,
          "sectionType": "TUNNEL"
        },
        {
          "startPointIndex": 0,
          "endPointIndex": 1,
          "sectionType": "PEDESTRIAN"
        },
        {
          "startPointIndex": 3,
          "endPointIndex": 4,
          "sectionType": "TRAFFIC",
          "simpleCategory": "JAM",
          "effectiveSpeedInKmh": 40,
          "delayInSeconds": 158,
          "magnitudeOfDelay": 1,
          "tec": {
            "effectCode": 4,
            "causes": [
              {
                "mainCauseCode": 1
              },
              {
                "mainCauseCode": 26,
                "subCauseCode": 2
              }
            ]
          }
        },
        [...further sections...]
      ],
      "guidance": {
        "instructions": [
          {
            "routeOffsetInMeters": 0,
            "travelTimeInSeconds": 0,
            "point": {
              "latitude": 52.50931,
              "longitude": 13.42937
            },
            "instructionType": "LOCATION_DEPARTURE",
            "street": "An der Schillingbrücke",
            "countryCode":"DEU",
            "possibleCombineWithNext": false,
            "drivingSide": "RIGHT",
            "maneuver": "DEPART",
            "message": "Leave from An der Schillingbrücke"
          },
          [...further instructions...]
        ],
        "instructionGroups": [
          {
            "firstInstructionIndex": 0,
            "lastInstructionIndex": 5,
            "groupLengthInMeters": 4567,
            "groupMessage": "Leave from An der Schillingbrücke and continue to A1/E35"
          },
          [...further instruction groups...]
        ]
      }
    }
    [...further routes...]
  ],
  "optimizedWaypoints": [
    {
      "providedIndex": 0,
      "optimizedIndex": 1
    },
    {
      "providedIndex": 1,
      "optimizedIndex": 0
    }
    [...further optimized waypoints...]
  ],
  "report": {
    "effectiveSettings": [
      {
        "key": "avoid",
        "value": "motorways"
      },
      {
        "key": "computeBestOrder",
        "value": "true"
      },
      [...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"?>
<calculateRouteResponse xmlns="http://api.tomtom.com/routing" formatVersion="0.0.12">
  <copyright>Copyright 2019 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"/>
</calculateRouteResponse>

The equivalent JSON error response would look like this:

{
  "formatVersion":"0.0.12",
  "copyright":"Copyright 2019 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

<optimizedWaypoints>
<waypoint providedIndex="0" optimizedIndex="1"/>
<waypoint providedIndex="1" optimizedIndex="2"/>
<waypoint providedIndex="2" optimizedIndex="0"/>
</optimizedWaypoints>

Structure of an instruction

Guidance instruction deprecation policy: As part of the continuous improvement of the Routing API, we also extend our guidance instructions with new features. In many cases, this requires the introduction of new maneuver codes for new types of instructions. Hence we cannot guarantee the same deprecation policy for guidance instructions as compared to the rest of the Routing API. In particular clients are expected to be forward compatible, we reserve the right to extend all enums defined below with new values. This includes completely new maneuver codes for new types of instructions. At the same time we reserve the right to retire enum values for instructions that are superseded by their improved counterparts no longer generated by the internal Guidance component. The same rules for forward-/backward-compatibility apply to fields for guidance instructions. For the retirement of instructions that are no longer relevant we give a deprecation period of 4 months. After this period we reserve the right to remove deprecated values at our convenience.

"point":{
"latitude":52.36965,
"longitude":4.70208
}

<point latitude="52.36965" longitude="4.70208"/>

"roadNumbers":["E34","N205"]

<roadNumbers>
  <roadNumber>E34</roadNumber>
  <roadNumber>N205</roadNumber>
</roadNumbers>

Maneuver codes

Possible values of the maneuver instruction field.

Example of a combined message

Sometimes it is possible to combine two successive instructions into a single instruction making it easier to follow. When this is the case the possibleCombineWithNext flag will be true.
For example:

10. Turn left onto Einsteinweg/A10/E22 towards Ring Amsterdam

11. Follow Einsteinweg/A10/E22 towards Ring Amsterdam

The possibleCombineWithNext flag on instruction 10 is true. This indicates to the clients of coded guidance that it can be combined with instruction 11. The instructions will be combined automatically for clients requesting human-readable guidance. The combinedMessage field contains the combined message:

Turn left onto Einsteinweg/A10/E22 towards Ring Amsterdam then follow Einsteinweg/A10/E22 towards Ring Amsterdam

Tagged messages

A human-readable message is built up from repeatable identified elements. These are tagged to allow client applications to format them correctly. The following message components are tagged when instructionsType=tagged:

Examples of tagged messages:

Turn left onto <roadNumber>A4</roadNumber>/<roadNumber>E19</roadNumber> towards <signpostText>Den Haag</signpostText>

Take exit no. <exitNumber>1</exitNumber> onto <street>Anderlechtlaan</street> towards <signpostText>Amsterdam-Sloten</signpostText>

Follow <street>Rijksweg A9</street>/<roadNumber>A9</roadNumber> towards <signpostText>Amstelveen</signpostText>

Structure of route sections

Structure of an error response

Engine error while executing route request: MAP_MATCHING_FAILURE: Origin (54.3226, 3.11463)
Engine error while executing route request: MAP_MATCHING_FAILURE: Waypoint 3 (54.3226, 3.11463)

Supported languages