Calculate Route

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.

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.

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/calculateRoute/locations/contentType?key=Your_API_Key
    &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
    &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
    &chargeMarginsInkWh=commaSeparatedFloats

GET URL example

Note: Linebreaks are designated by "\".

https://api.tomtom.com/routing/1/calculateRoute/\
52.50931,13.42936:52.50274,13.43872/json?\
instructionsType=text&language=en-US\
&vehicleHeading=90&sectionType=traffic\
&report=effectiveSettings&routeType=eco\
&traffic=true&avoid=unpavedRoads\
&travelMode=car&vehicleMaxSpeed=120\
&vehicleCommercial=false&vehicleEngineType=combustion\
&key=Your_API_Key

GET curl command

Note: Linebreaks are designated by "\".

curl -X GET "https://api.tomtom.com/routing/1/calculateRoute/\
52.50931,13.42936:52.50274,13.43872/json?\
instructionsType=text&language=en-US&vehicleHeading=90\
&sectionType=traffic&report=effectiveSettings\
&routeType=eco&traffic=true&avoid=unpavedRoads\
&travelMode=car&vehicleMaxSpeed=120&vehicleCommercial=false\
&vehicleEngineType=combustion&key=Your_API_Key" -H "accept:*/*"

POST URL example

For ease of viewing and identification:

• Required constants and parameters are shown in bold text.
• Optional parameters are shown in plain text.

https://api.tomtom.com/routing/1/calculateRoute/52.50931,13.42936:52.50274,13.43872/json?key=Your_API_Key

POST curl command

curl -X POST "https://api.tomtom.com/routing/1/calculateRoute/52.50931,13.42936:52.50274,13.43872/json?key=Your_API_Key"\
  -H "Content-type:application/json" -d\
  '{
    "supportingPoints":[
      {
        "latitude": 52.50930, "longitude": 13.42936
      },
      {
        "latitude":52.50844, "longitude": 13.42859
      }
    ],
    "avoidVignette": [
      "AUS","CHE"
    ]
  }'

Types

The following data table describes a subset of the types that can be used in the Calculate Route service; the remaining types are listed on the Common Routing Parameters page.

Type	Description
circle	A circle with a center point and a radius (in meters). The radius must be a positive integer with the maximum value of 135000. Example: circle(52.37245,4.89406,10000)
location	A point or a circle. Example: 52.37245,4.89406 circle(52.37245,4.89406,10000)
commaSeparatedFloats	Comma-separated list of floats. Example: 1.23,0

Headers

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

Request parameters

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

• There are no required parameters. All of the following parameters are optional.
• 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 these optional request parameters is not important.

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 vehicle consumption model.

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

• When the 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

The <supportingPoints> XML element 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 the calculation of the reference route's travel time and traffic delay.

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 following table describes a subset of the parameters that can be used in the Calculate Route service; the remaining parameters are listed on the Common Routing Parameters 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>
  <reassessmentParameterSets>
    <reassessmentParameterSet>
      <auxiliaryPowerInkW>0.3</auxiliaryPowerInkW>
    </reassessmentParameterSet>
  </reassessmentParameterSets>
</postData>

The <postData> XML 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"
  ],
  "reassessmentParameterSets": [
    {
      "auxiliaryPowerInkW": 0.3
    }
  ]
}

Response headers

There currently are no additional response headers specific to the Calculate Route 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 Route service; the common response codes are listed on the Common Routing Parameters page.

Example of a successful response

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

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

An XML response could look like this: (Note: Comments are in italics.)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<calculateRouteResponse xmlns="http://api.tomtom.com/routing" formatVersion="0.0.12">
  <route>
    <summary>
      <lengthInMeters>1147</lengthInMeters>
      <travelTimeInSeconds>161</travelTimeInSeconds>
      <trafficDelayInSeconds>15</trafficDelayInSeconds>
      <trafficLengthInMeters>147</trafficLengthInMeters>
      <departureTime>2015-04-02T14:58:40+02:00</departureTime>
      <arrivalTime>2015-04-02T15:01:21+02:00</arrivalTime>
      <noTrafficTravelTimeInSeconds>120</noTrafficTravelTimeInSeconds>
      <historicTrafficTravelTimeInSeconds>157</historicTrafficTravelTimeInSeconds>
      <liveTrafficIncidentsTravelTimeInSeconds>161</liveTrafficIncidentsTravelTimeInSeconds>
      <batteryConsumptionInkWh>0.155</batteryConsumptionInkWh>
      <deviationDistance>1735</deviationDistance>
      <deviationTime>127</deviationTime>
      <deviationPoint latitude="52.50904" longitude="13.42912"/>
      <reachableRouteOffsets>
        <reachableRouteOffset>
          <chargeMarginInkWh>0.0</chargeMarginInkWh>
          <routeOffsetInMeters>1147</routeOffsetInMeters>
          <point latitude="52.51565" longitude="13.43979"/>
          <pointIndex>50</pointIndex>
        </reachableRouteOffset>
      </reachableRouteOffsets>
    </summary>
    <routeReassessments>
      <routeReassessment>
        <batteryConsumptionInkWh>0.2</batteryConsumptionInkWh>
        <reachableRouteOffsets>
          <reachableRouteOffset>
            <chargeMarginInkWh>0.0</chargeMarginInkWh>
            <routeOffsetInMeters>1147</routeOffsetInMeters>
            <point latitude="52.51565" longitude="13.43979"/>
            <pointIndex>50</pointIndex>
          </reachableRouteOffset>
        </reachableRouteOffsets>
      </routeReassessment>
    </routeReassessments>
    <leg>
      <summary>
        <lengthInMeters>108</lengthInMeters>
        <travelTimeInSeconds>11</travelTimeInSeconds>
        <trafficDelayInSeconds>0</trafficDelayInSeconds>
        <trafficLengthInMeters>0</trafficLengthInMeters>
        <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>11</liveTrafficIncidentsTravelTimeInSeconds>
        <batteryConsumptionInkWh>0.1</batteryConsumptionInkWh>
      </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"/>
          <pointIndex>0</pointIndex>
          <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: (Note: Comments are in italics.)

{
  "formatVersion": "0.0.12",
  "routes": [
    {
      "summary": {
        "lengthInMeters": 1147,
        "travelTimeInSeconds": 161,
        "trafficDelayInSeconds": 15,
        "trafficLengthInMeters": 147,
        "departureTime": "2015-04-02T15:01:57+02:00",
        "arrivalTime": "2015-04-02T15:04:38+02:00",
        "noTrafficTravelTimeInSeconds": 120,
        "historicTrafficTravelTimeInSeconds": 157,
        "liveTrafficIncidentsTravelTimeInSeconds": 161,
        "batteryConsumptionInkWh": 0.155,
        "deviationDistance": 1735,
        "deviationTime": 127,
        "deviationPoint": {
          "latitude": 52.50904,
          "longitude": 13.42912
        },
        "reachableRouteOffsets": [
          {
            "chargeMarginInkWh": 0.0,
            "routeOffsetInMeters": 1147,
            "point": {
              "latitude": 52.51565,
              "longitude": 13.43979
            },
            "pointIndex": 50
          }
        ]
      },
      "routeReassessments": [
        {
          "batteryConsumptionInkWh": 0.2,
          "reachableRouteOffsets": [
            {
              "chargeMarginInkWh": 0.0,
              "routeOffsetInMeters": 1147,
              "point": {
                "latitude": 52.51565,
                "longitude": 13.43979
              },
              "pointIndex": 50
            }
          ]
        }
      ],
      "legs": [
        {
          "summary": {
            "lengthInMeters": 108,
            "travelTimeInSeconds": 11,
            "trafficDelayInSeconds": 0,
            "trafficLengthInMeters": 0,
            "departureTime": "2015-04-02T15:01:57+02:00",
            "arrivalTime": "2015-04-02T15:02:07+02:00",
            "noTrafficTravelTimeInSeconds": 10,
            "historicTrafficTravelTimeInSeconds": 11,
            "liveTrafficIncidentsTravelTimeInSeconds": 11,
            "batteryConsumptionInkWh": 0.1
          },
          "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
            },
            "pointIndex": 0,
            "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">
  <error description="Error description (same as calculateRouteResponse/detailedError/@message)">
  <detailedError>
    <code> error code </code>
    <message> "Error message" </message>
  </detailedError>
</calculateRouteResponse>

The equivalent JSON error response would look like this:

{
  "formatVersion":"0.0.12",
  "error":{
    "description":"Error description (same as detailedError["message"])"
  },
  "detailedError": {
    "code": <error code>,
    "message": "Error message"
  }
}

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 elements)

The following table describes the possible values of the <maneuver> instruction field.

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 message

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

Take exit message

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

Follow message

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

Structure of route sections

The following language code abbreviations are also supported: