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

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.

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.

Type Description Example
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. circle(52.37245,4.89406,10000)
location A point or a circle.
  • 52.37245,4.89406
  • circle(52.37245,4.89406,10000)

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.

Parameter Description Req'd? Type / Values Default Value
versionNumber Service version number. The current value is 1. Yes 1
locations Locations through which the route is calculated. The following constraints apply:

  • At least two locations must be provided.
  • The first location in the sequence defines the origin and must be of type point.
  • The last location in the sequence defines the destination and must be of type point.
  • One or more optional intermediate locations (known as waypoints) may be provided:
    • The maximum allowed number of waypoints is 150.
    • A point waypoint results in an extra leg in the response, a circle waypoint does not.
    • Circle waypoints cannot be used when computeBestOrder is true.
Yes Colon-delimited locations.

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.

Parameter Description Req'd? Type / Values Default Value Max Value
[maxAlternatives] Number of desired alternative routes to be calculated. The value provided:

  • must be an integer in the range 0-5
  • using a value greater than 0 in conjunction with computeBestOrder set to true is not allowed
  • fewer alternative routes may be returned if either fewer alternatives exist or the requested number of alternatives is larger than the service can calculate.
No integer 0 5
[alternativeType] Allows to specify whether to compute alternatives with the objective to find routes that are significantly different, or whether to look for routes better than the reference route. Possible values are:

  • anyRoute: compute alternative routes that are significantly different from the reference route.
  • betterRoute: return an alternative route only if it is better than the reference route according to the given planning criteria. If there is a road block on the reference route then any alternative that does not contain blockages is considered as a better route.

Can only be used when reconstructing a route.

No
  • anyRoute
  • betterRoute
anyRoute
[minDeviationDistance] All alternative routes returned will follow the reference route (see section POST Requests) from the origin point of the calculateRoute request for at least this number of meters. Can only be used when reconstructing a route. The minDeviationDistance parameter cannot be used in conjunction with arriveAt. No integer 0
[minDeviationTime] All alternative routes returned will follow the reference route (see section POST Requests) from the origin point of the calculateRoute request for at least this number of seconds. Can only be used when reconstructing a route. The minDeviationTime parameter cannot be used in conjunction with arriveAt. No integer 0
[instructionsType] If specified, guidance instructions will be returned (if available).

Possible values:

  • coded returns raw instruction data without human-readable messages.
  • text returns raw instructions data with human-readable messages in plain text.
  • tagged returns raw instruction data with tagged human-readable messages to permit formatting.

Note that the instructionsType parameter cannot be used in conjunction with routeRepresentation=none.

If alternative routes are requested, instructions will be generated for each route returned.

See the Tagged messages section for more information about tagged messages.

No
  • coded
  • text
  • tagged
[language] The language parameter determines the language of the guidance messages. It does not affect proper nouns (the names of streets, plazas, etc.) It has no effect when instructionsType=coded.

Allowed values are (a subset of) the IETF language tags described here. The currently supported languages are listed in the supported languages section below.

No string en-GB
[computeBestOrder] Re-order the route waypoints with a fast heuristic algorithm to reduce the overall route length. Yields best results when used in conjunction with routeType shortest. Possible values:

  • true (compute a better order, if possible; not allowed to be used in conjunction with maxAlternatives value greater than 0; not allowed to be used in conjunction with circle waypoints). The response will include the optimized waypoint indices.
  • false (use the locations in the given order). Not allowed to be used in conjunction with routeRepresentation none.
No boolean false
[routeRepresentation] Specifies the representation of the set of routes provided as response. Possible values:

  • polyline includes routes in the response.
  • summaryOnly as per polyline, but excluding the <points> elements for the routes in the response.
  • none includes only the optimized waypoint indices but does not include the routes in the response. This parameter value can only be used in conjunction with computeBestOrder true.
No
  • polyline
  • summaryOnly
  • none
polyline
[computeTravelTimeFor] Specifies whether to return additional travel times using different types of traffic information (none, historic, live) as well as the default best-estimate travel time. Possible values:

  • none - do not compute additional travel times,
  • all - compute travel times for all types of traffic information. Specifying all results in the fields noTrafficTravelTimeInSeconds, historicTrafficTravelTimeInSeconds and liveTrafficIncidentsTravelTimeInSeconds being included in the summaries in the route response.
No
  • none
  • all
none
[vehicleHeading] The directional heading of the vehicle in degrees starting at true North and continuing in clockwise direction. North is 0 degrees, east is 90 degrees, south is 180 degrees, west is 270 degrees. Possible values 0-359. No integer 359
[sectionType] Specifies which of the section types is reported in the route response. Can be specified multiple times.

  • carTrain, ferry, tunnel or motorway: get
    sections if the route includes car trains, ferries, tunnels, or motorways
  • pedestrian: sections which are suited for pedestrians only
  • tollRoad: sections which require a toll to be payed
  • tollVignette: sections which require a toll vignette to be present
  • country: countries the route has parts in
  • travelMode: sections in relation to the request parameter travelMode
  • traffic: sections which contain traffic information
No
  • carTrain
  • country
  • ferry
  • motorway
  • pedestrian
  • tollRoad
  • tollVignette
  • traffic
  • travelMode
  • tunnel
travelMode

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.

Parameter Description
<supportingPoints> A list of base route points, defined as <supportingPoint>, to be used as input for route reconstruction.
<supportingPoint> A base route point, defined as a latitude longitude pair, to be used as input for route reconstruction.

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 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>
  <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 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.",
  "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 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"/>
</calculateRouteResponse>

The equivalent JSON error response would look like this:

{
  "formatVersion":"0.0.12",
  "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
<calculateRouteResponse> Main response element.
<route> A description of a route comprised of a list of legs.
<summary> A summary of a route, or a route leg.
<leg> A description of a part of a route, comprised of a list of points. Each additional waypoint provided in the request will result in an additional leg in the returned route.
<points> List of <point> elements.
<point> A location on the surface of the globe defined as a latitude longitude pair.
<sections> Available inside <route> elements. Contains one or more <section> elements.
The inner structure of <section> is given below.
<startPointIndex> Index of the first point (offset 0) in the route this section applies to (only included for routeRepresentation polyline).
<endPointIndex> Index of the last point (offset 0) in the route this section applies to (only included for routeRepresentation polyline).
<countryCode> 3-character ISO 3166-1 alpha-3 country code.
<simpleCategory> Type of the incident. Can currently be JAM, ROAD_WORK, ROAD_CLOSURE, or OTHER. See <tec> for detailed information.
<effectiveSpeedInKmh> Effective speed of the incident in km/h, averaged over its entire length.
<delayInSeconds> Delay in seconds caused by the incident.
<magnitudeOfDelay> The magnitude of delay caused by the incident.

Possible values:

  • 0: unknown
  • 1: minor
  • 2: moderate
  • 3: major
  • 4: undefined, used for road closures and other indefinite delays

These values correspond to the values of the response field <ty> of the Traffic Incident Details.

<tec> Details of the traffic event, using definitions in the TPEG2-TEC standard. Can contain <effectCode> and <causes> elements.
<effectCode> The effect on the traffic flow. Contains a value in the tec001:EffectCode table, as defined in the TPEG2-TEC standard. Can be used to color-code traffic events according to severity.
<causes> List of <cause> elements.
<cause> The cause of the traffic event. Can contain <mainCauseCode> and <subCauseCode> elements. Can be used to define iconography and descriptions.
<mainCauseCode> The main cause of the traffic event. Contains a value in the tec002:CauseCode table, as defined in the TPEG2-TEC standard.
<subCauseCode> The subcause of the traffic event. Contains a value in the sub cause table defined by the mainCauseCode, as defined in the TPEG2-TEC standard.
<lengthInMeters> The route or leg length in meters.
<travelTimeInSeconds> Estimated travel time in seconds. Note that even when traffic=false travelTimeInSeconds still includes the delay due to traffic.
<trafficDelayInSeconds> Delay in seconds compared to free-flow conditions according to real-time traffic information.
<noTrafficTravelTimeInSeconds> Estimated travel time in seconds calculated as if there are no delays on the route due to traffic conditions (e.g. congestion). Included if requested using computeTravelTimeFor parameter.
<historicTrafficTravelTimeInSeconds> Estimated travel time in seconds calculated using time-dependent historic traffic data. Included if requested using computeTravelTimeFor parameter.
<liveTrafficIncidentsTravelTimeInSeconds> Estimated travel time in seconds calculated using real-time speed data. Included if requested using computeTravelTimeFor parameter.
<deviationDistance> The distance (in meters) from the origin point of the calculateRoute request to the first point where this route forks off from the reference route. If the route is identical to the reference route, then this field is set to the length of the route. Included in all alternative (but not reference) route summary fields.
<deviationTime> The travel time (in seconds) from the origin point of the calculateRoute request to the first point where this route forks off from the reference route. If the route is identical to the reference route, then this field is set to the estimated travel time of the route. Included in all alternative (but not reference) route summary fields.
<deviationPoint> The coordinates of the first point following the origin point of the calculateRoute request where this route forks off from the reference route. If the route is identical to the reference route, then this field is set to the coordinates of the last point on the route. Included in all alternative (but not reference) route summary fields.
<fuelConsumptionInLiters> Estimated fuel consumption in liters using the Combustion Consumption Model. Included if vehicleEngineType is set to combustion and constantSpeedConsumptionInLitersPerHundredkm is specified. The value will be non-negative.
<batteryConsumptionInkWh> Estimated electric energy consumption in kilowatt hours (kWh) using the Electric Consumption Model. Included if vehicleEngineType is set to electric and constantSpeedConsumptionInkWhPerHundredkm is specified.
The value of batteryConsumptionInkWh includes the recuperated electric energy and can therefore be negative (which indicates gaining energy). If both maxChargeInkWh and currentChargeInkWh are specified, recuperation will be capped to ensure that the battery charge level never exceeds maxChargeInkWh. If neither maxChargeInkWh nor currentChargeInkWh are specified, unconstrained recuperation is assumed in the consumption calculation.
<optimizedWaypoints> Optimized sequence of waypoints. It shows the index from the user provided waypoint sequence for the original and optimized list. For instance, a response:

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

means that the original sequence is [0, 1, 2] and optimized sequence is [1, 2, 0]. Since the index starts by 0 the original is "first, second, third" while the optimized is "second, third, first".

<waypoint> Each of the elements of the list <optimizedWaypoints>. It contains the indices for that waypoint in the provided and optimized list.
<departureTime> The estimated departure time for the route or leg. Specified as a dateTime.
<arrivalTime> The estimated arrival time for the route or leg. Specified as a dateTime.
<guidance> Contains guidance related elements. This field is present only when guidance was requested and is available.
<instruction> A set of attributes describing a maneuver, e.g. 'Turn right', 'Keep left', 'Take the ferry', 'Take the motorway', 'Arrive'.
<instructionGroup> Groups a sequence of instruction elements which are related to each other. The sequence range is constrained with firstInstructionIndex and lastInstructionIndex. When human-readable text messages are requested for guidance (instructionType=text or tagged), then the instructionGroup has a summary message returned when available.
<effectiveSettings> Effective parameters or data used when calling the Calculate Route API.
<statusCode> Original HTTP status code as listed in Response Codes (included for content type jsonp only).

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.

Field Description Type
<routeOffsetInMeters> Distance from the start of the route to the point of the instruction. integer
<travelTimeInSeconds> Estimated travel time up to the point corresponding to routeOffsetInMeters. integer
<point> A location of the maneuver defined as a latitude longitude pair. Example:

JSON:

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

<point latitude="52.36965" longitude="4.70208"/>
latitude longitude pair
<instructionType> Type of the instruction, e.g., turn or change of road form.

Possible values:

  • TURN
  • ROAD_CHANGE
  • LOCATION_DEPARTURE
  • LOCATION_ARRIVAL
  • DIRECTION_INFO
  • LOCATION_WAYPOINT
enum
<roadNumbers> An aggregate for roadNumber elements. Example:

JSON:

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

<roadNumbers>
  <roadNumber>E34</roadNumber>
  <roadNumber>N205</roadNumber>
</roadNumbers>
array
<roadNumber> Road number of the next significant road segment after the maneuver, or of the road that has to be followed. string
<exitNumber> The number(s) of a highway exit taken by the current maneuver. If an exit has multiple exit numbers, they will be separated by "," and possibly aggregated by "-", e.g. "10, 13-15". string
<street> Street name of the next significant road segment after the maneuver, or of the street that should be followed. string
<signpostText> Text on a signpost which is most relevant to the maneuver, or to the direction that should be followed. string
<countryCode> 3-character ISO 3166-1 alpha-3 country code. string
<stateCode> Subdivision (e.g. state) of the country, represented by the second part of an ISO 3166-2 code. This is only available for some countries, such as the US, Canada, and Mexico. string
<junctionType> Type of the junction at which the maneuver takes place.

For larger roundabouts two separate instructions are generated for entering and leaving the roundabout.

Possible values:

  • REGULAR
  • ROUNDABOUT
  • BIFURCATION
enum
<turnAngleInDecimalDegrees> Indicates the direction of an instruction. If junctionType indicates a turn instruction:

  • -180 = U-turn
  • -179 .. -1 = left turn
  • 0 = straight on (a '0 degree' turn)
  • 1 .. 179 = right turn

If junctionType indicates a bifurcation instruction:

  • <0 - keep left
  • >0 - keep right
integer
<roundaboutExitNumber> Indicates which exit to take at a roundabout. integer
<possibleCombineWithNext> It is possible to optionally combine the instruction with the next one. This can be used to build messages like "Turn left and then turn right".

Possible values:

  • true
  • false
boolean
<drivingSide> Indicates left-hand vs. right-hand side driving at the point of the maneuver.

Possible values:

  • LEFT
  • RIGHT
enum
<maneuver> A code identifying the maneuver (e.g. 'Turn right').

See maneuver codes

enum
<message> A human-readable message for the maneuver. string
<combinedMessage> A human-readable message for the maneuver combined with the message from the next instruction.

See example of a combined message

string

Maneuver codes

Possible values of the maneuver instruction field.

Maneuver code Example translation
ARRIVE You have arrived.
ARRIVE_LEFT You have arrived. Your destination is on the left.
ARRIVE_RIGHT You have arrived. Your destination is on the right.
DEPART Leave.
STRAIGHT Keep straight on.
KEEP_RIGHT Keep right.
BEAR_RIGHT Bear right.
TURN_RIGHT Turn right.
SHARP_RIGHT Turn sharp right.
KEEP_LEFT Keep left.
BEAR_LEFT Bear left.
TURN_LEFT Turn left.
SHARP_LEFT Turn sharp left.
MAKE_UTURN Make a U-turn.
ENTER_MOTORWAY Take the motorway.
ENTER_FREEWAY Take the freeway.
ENTER_HIGHWAY Take the highway.
TAKE_EXIT Take the exit.
MOTORWAY_EXIT_LEFT Take the left exit.
MOTORWAY_EXIT_RIGHT Take the right exit.
TAKE_FERRY Take the ferry.
ROUNDABOUT_CROSS Cross the roundabout.
ROUNDABOUT_RIGHT At the roundabout take the exit on the right.
ROUNDABOUT_LEFT At the roundabout take the exit on the left.
ROUNDABOUT_BACK Go around the roundabout.
TRY_MAKE_UTURN Try to make a U-turn.
FOLLOW Follow.
SWITCH_PARALLEL_ROAD Switch to the parallel road.
SWITCH_MAIN_ROAD Switch to the main road.
ENTRANCE_RAMP Take the ramp.
WAYPOINT_LEFT You have reached the waypoint. It is on the left.
WAYPOINT_RIGHT You have reached the waypoint. It is on the right.
WAYPOINT_REACHED You have reached the waypoint.

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:

Message Component Tags
Street or road name street
Road number roadNumber
Signpost text signpostText
Exit number - motorway exitNumber
Exit number - roundabout roundaboutExitNumber

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

Field Description
<section> Sections contain additional information about parts of a route. Each <section>
contains at least the elements <startPointIndex>,
<endPointIndex>, and <sectionType>.
<sectionType> contains the response section type

request section type response section type
carTrain CAR_TRAIN
country COUNTRY
ferry FERRY
motorway MOTORWAY
pedestrian PEDESTRIAN
tollRoad TOLL_ROAD
tollVignette TOLL_VIGNETTE
traffic TRAFFIC
travelMode TRAVEL_MODE
tunnel TUNNEL

The COUNTRY sections span between country border crossings,
from the departure, or to the destination. The section additionally contains
<countryCode>.
If the route has disjoint parts in the same country, there will be several sections with the same countryCode.
If no country can be assigned to a part of the route, as for example in international waters,
there may be no country section for this part.

A TOLL_VIGNETTE section additionally contains a
<countryCode> since toll vignettes are often specific to a country.
Note that a toll vignette section shows up as a toll road section, too.

A TRAFFIC section may additionally contain any of the following: <simpleCategory>, <effectiveSpeedInKmh>, <delayInSeconds>, <magnitudeOfDelay>, <tec>.

TRAVEL_MODE sections cover the whole route. Each section's travel mode is
reported in <travelMode>.

<travelMode> This attribute is either set to the value given to the request parameter
travelMode, if this travel mode is possible, or to other which indicates that the given mode
of transport is not possible in this section. This field can only be used within sections
of type TRAVEL_MODE.

Structure of an error response

Field Description
<calculateRouteResponse> Main response element.
<error> Contains an error description field with a human readable error message.
It is a freeform string which may be extended in the future, so it is recommended to only match substrings of the description.
The error description field always contains an error code. The (non complete) list of error codes is:

Error code Description
MAP_MATCHING_FAILURE One of the input points (Origin, Destination, Waypoints) could not be matched to the map because there is no known drivable section near this point.
This error code is always followed by a description of one point that was not matchable:

  • Origin (Latitude, Longitude)
  • Destination (Latitude, Longitude)
  • Waypoint N (Latitude, Longitude)
NO_ROUTE_FOUND The was no valid route found.
CANNOT_RESTORE_BASEROUTE The route reconstruction using supportingPoints failed.
BAD_INPUT Some input parameter combination was not valid.

Example of a description string:

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

Supported languages

Language Name Language Tag
Afrikaans (South Africa) af-ZA
Arabic ar
Bulgarian bg-BG
Chinese (Taiwan) zh-TW
Czech cs-CZ
Danish da-DK
Dutch nl-NL
English (Great Britain) en-GB
English (USA) en-US
Finnish fi-FI
French fr-FR
German de-DE
Greek el-GR
Hungarian hu-HU
Indonesian id-ID
Italian it-IT
Korean ko-KR
Lithuanian lt-LT
Malay ms-MY
Norwegian nb-NO
Polish pl-PL
Portuguese (Brazil) pt-BR
Portuguese (Portugal) pt-PT
Russian ru-RU
Slovak sk-SK
Slovenian sl-SI
Spanish (Castilian) es-ES
Spanish (Mexico) es-MX
Swedish sv-SE
Thai th-TH
Turkish tr-TR