Calculate Route

Latitude, longitude pair (in EPSG:4326 projection), with the following constraints:

• Latitude values must be in the range [-90, +90].

• Longitude values must be in the range [-180, +180].

Example: 52.37245,4.89406

A location represented as a JSON object. The object should contain the two fields latitude and longitude each containing a number, and expressed in the same reference frame and with the same constraints as for the location type. Example: {“latitude”: 52.37245, “longitude”: 4.89406}

A date and time specified in RFC 3339 format with an optional time zone offset. Examples:

• 2023-12-19T16:39:57
• 2023-12-19T16:39:57-08:00

Avoids toll roads.

Avoids motorways.

Note: Avoiding motorways for long routes of approximately 500km+ may result in computation timeouts of the primary route or path alternatives.

Avoids ferries.

Avoids unpaved roads.

Avoids routes that require use of carpool (HOV/High Occupancy Vehicle) lanes.

Avoids using the same road multiple times.
This is most useful in conjunction with routeType=thrilling.

Avoids crossing country borders.

Avoids tunnels.

Avoids car trains.

Authorization key to access the API. Value: Your valid API Key.

Specifies which response fields to include using dot-notation. Fields marked as EXPLICIT in the response documentation must be explicitly listed in this header to be included in the response. See the Response field selection section for details and examples.

Specifies the MIME type of the body of the request. Value: application/json

Specifies API version
Value: 3

Specifies the MIME type of the body of the response.
Default value and only allowed value: application/json

Requests that the response be compressed. Value: gzip

Specifies the compression used for the request body. Currently, only gzip is supported. If not specified, no compression is assumed. This is equal to specifying identity.

Values:

• identity
• gzip

Specifies an identifier for the request.

• The value should be unique for each request.

• The value must match the regular expression ’^[a-zA-Z0-9-_\.]{1,100}$’.

• If specified, the same value is sent back in the similar-named response header. Otherwise, a generated value may be sent back.

Specifies which response fields to exclude using dot-notation. The exclusion is applied after the inclusion list and overrides it. See the Response field selection section for details and examples.

Determines the language of the returned names of places and phonetic translations in guidance.

• Proper nouns (the names of streets, plazas, etc.) are returned in the specified language, or if that is not available, they are returned in an available language that is close to it.

• The currently supported languages are listed in the Supported Languages page.

If the selected language isn’t supported, en-GB is used instead.

Base URL for calling the API.
Value: api.tomtom.com (The default global API endpoint.)

Specifies the API version.
Only allowed value: 3

Locations through which the route is calculated.
Contains fields origin and destination, and may contain field waypoints.
For the details, please see the RoutePlanningLocations section.

The date and time of departure from the origin point.

• Departure times apart from now must be specified as a dateTime.

• When a time zone offset is not specified, it is assumed to be that of the origin point.

• The departureDateTime parameter cannot be used in conjunction with arrivalDateTime.

Default value: now
Other value: dateTime

The date and time of arrival at the destination point.

• It must be specified as a dateTime.

• When a time zone offset is not specified, it is assumed to be that of the destination point.

The arrivalDateTime parameter cannot be used in conjunction with:

• departureDateTime

Value: dateTime

Specifies something that the route calculation should try to avoid when determining the route. It can contain one or more possible values listed under Avoids parameter possible values and provided as an array of strings. If specified, the array must not be empty. Avoid values are applied to all route legs. Must not be used together with per-leg avoids parameter. Must be omitted if not needed.

Defines areas of certain shapes that should be avoided when planning routes. Supported shapes include rectangles. It can contain one of each supported shapes fields.

This is an array of GeoJSON Feature objects with a maximum of ten elements. Each object describes an axis-aligned rectangle.
Each element must contain the fields type, bbox and geometry and must not contain any additional fields.

• The maximum size of a rectangle is about 160x160 km.

• It cannot cross the 180th meridian.

• It must be between -80 and +80 degrees of latitude.

Must have the value Feature

Represents the area of the rectangle to be avoided. The array must contain exactly 4 numbers.
The first two numbers represent the longitude and latitude (in that order) of the south west corner.
The following two numbers represent the longitude and latitude (in that order) of the north east corner.
[southWestLongitude, southWestLatitude, northEastLongitude, northEastLatitude]

Must be null.

Locations to be used as input for route reconstruction.

• The specified GeoJSON object must contain only the following 2 fields: type and coordinates.

• The type field must have the value LineString.

• The coordinates field must be an array of GeoJSON positions. Each element of the array represents one point of the input route and is represented as an array of exactly 2 numbers: [longitude, latitude].

• The coordinates array must have at least 2 elements.

For more information on representing route geometry formats, see the GeoJSON format section.

An array of objects with the parameters for the computation of each leg. If the parameter is such that it is available for use in the query parameters, then its simultaneous use in the query parameters and in the POST data is prohibited, and such a request will be returned with an error.
If the legs field is present in the POST data, then the number of elements in the array must be equal to the number of waypoints + 1.
If there is no need to specify any parameters for some leg, then an empty object must be specified.
It may contain the following fields:

• routeType: specifies the type of optimization used when calculating the leg. For the details, please see the Request parameters section.
  Default value: fast

• routeStop: an object of RouteStop type with additional parameters for the stop at the end of the current leg. It must be omitted if not needed.

• path: A GeoJSON object of type LineString, to be used as input for leg reconstruction.
  path cannot be used for the entire route and per leg simultaneously.
  The coordinates array inside the path must cover the whole leg, and the itinerary points (an origin, a destination, or a waypoint) must be located at (or very near to) the first and last points.
  path parameter must be omitted if not needed.
  When path is specified, the coordinates array in it must have at least two elements.
  For more information on the GeoJSON format, see the GeoJSON format section.

• avoids: An array of objects of type Route avoid . Must be omitted if not needed. Must not be used together with the route-level POST parameter avoids.

The directional heading of the vehicle, in degrees starting at true North and continuing in a clockwise direction.

• North is 0 degrees.

• East is 90 degrees.

• South is 180 degrees.

• West is 270 degrees.

Maximum value: 359
Other values: 0-359

Specifies that the route calculation should try to avoid ETC-transponder-only toll roads when determining the route if a vehicle does not have an ETC transponder. Possible values are:

• all: Do not avoid ETC-transponder-only toll roads.
• none: Avoids ETC-transponder-only toll roads.

Default value: all

Maximum speed of the vehicle in kilometers/hour.

• Must have a value in the range [0, 250].

• A value of 0 means that an appropriate value for the vehicle will be determined and applied during route planning.

Default value: 0

Weight of the vehicle in kilograms.
When the value is positive then the calculated route respects weight restrictions.
Default value: 0
Minimum value: 0

Number of desired path alternative routes to be calculated. The value provided:

• Must be an integer in the range 0-5.

• Fewer path alternative routes may be returned if either fewer path alternatives exist, or the requested number of path alternatives is larger than the service can calculate.

Default value: 0
Maximum value: 5

Decides how traffic is considered for computing routes.
Possible values are:

• live: In addition to historical travel durations, routing and estimated travel durations consider traffic jams and short- and long-term closures during the travel time window.

• historical: Routing and estimated travel duration consider historical travel durations and long term closures. Traffic jams and short-term closures during the travel time window do not influence routing or travel duration.

Default value: live

Specifies the type of optimization used when calculating routes. Possible values are:

• fast: Route calculation is optimized by travel duration, while keeping the routes sensible. For example, the calculation may avoid shortcuts along inconvenient side roads or long detours that only save very little time.

• short: Route calculation is optimized such that a good compromise between small travel duration and short travel distance is achieved.

  • Use short only for short to medium-distance routes. It explores a much larger search space than fast, so on long-distance routes — especially when combined with waypoints or avoid options — it can exceed the server’s compute time limit and the request will fail with a timeout. For long-distance planning, use fast instead. See the FAQ entry How can I reduce the response time? for the full list of parameters that increase compute time.

• efficient: Route calculation is optimized such that a good compromise between small travel duration and low fuel or energy consumption is achieved.

• thrilling: Route calculation is optimized such that routes include interesting or challenging roads and use as few motorways as possible.

  • There is a limit of 900km on routes planned with routeType=thrilling.

Default value: fast

Default value and only allowed value: car.

The engine type of the vehicle. Default value: combustion Other value: electric

Specifies the preference of roadside on arrival to waypoints and destination. Stop on the road has to be set at least two meters to the preferred side, otherwise the behavior will default to anySide. Possible values are:

• anySide: Both sides of a road could be used to approach the waypoint and destination. When a vehicle arrives, a stop could be either on a left side or a right side.

• curbSide: Ensures a minimal number of road crossings at waypoints or the destination. When a vehicle arrives, a stop should be on the right for the right-side driving road or on a left for the left-side driving road.

Default value: anySide Other value: curbSide

Origin location for the route calculation.

• The specified GeoJSON object must contain only the following 2 fields: type and coordinates.

• The type field must have the value Point.

• The coordinates field must be a single GeoJSON position, represented as an array of exactly 2 numbers: [longitude, latitude].

For more information, see the GeoJSON format section.

Optional, intermediate waypoint locations for the route calculation.

• The specified GeoJSON object must contain only the following 2 fields: type and coordinates.

• The type field must have the value MultiPoint.

• The coordinates field must be an array of GeoJSON positions. Each element of the array represents a waypoint and is represented as an array of exactly 2 numbers: [longitude, latitude]. The array must contain at least one element if waypoints are specified.

• The waypoints are used in the order they appear in the array.

• The maximum allowed number of waypoints is 150.

• A waypoint of type location results in an extra leg in the response.

For more information, see the GeoJSON format section.

Destination location for the route calculation.

• The specified GeoJSON object must contain only the following 2 fields: type and coordinates.

• The type field must have the value Point.

• The coordinates field must be a single GeoJSON position, represented as an array of exactly 2 numbers: [longitude, latitude].

For more information, see the GeoJSON format section.

Specifies the waiting duration at route stops. It must be 0 in the last leg (the destination).
Default value: 0

Specifies the entry points for the stop at the end of the current leg in GeoJSON MultiPoint format. The route to the stop is calculated based on these entry points.

• Entries with the same location are not allowed.

• If specified, the coordinates array must not be empty.

For more details about GeoJSON, refer to the RFC 7946 .

Specifies the name of the road attribute to configure.
Possible values are listed under Avoids parameter possible values .

The service whitelists response headers that browsers are allowed to access.
Value: Content-Length

The service allows cross-origin resource sharing.
Value: * (wildcard)

The service supports HTTP compression if requested by the client.
Value: gzip

The language used when assembling the response, for example, selecting localized place names, phonetic translations, or other language‑dependent fields.
Note that the returned content may still include text in other languages, depending on data availability and other factors.

The format of the response.
Value: application/json; charset=utf-8

The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain. It is supported by HTTP/1.1 clients. It may not be supported by HTTP/1.0 clients.
Values:

• no-cache
• no-transform

This is an identifier for the request. If Tracking-ID was specified in the request headers, it contains the same value. Otherwise it may contain a generated value.

OK: A route or range was calculated and the body of the response contains the data for a successful response.

Bad request: One or more parameters were:

• Incorrectly specified.

• Are mutually exclusive.

• The points in the route request are not connected by the road network.

• The points in the request are not near enough to a road.

Permission or authentication issues:

• Forbidden

• Not authorized

• Account inactive

Not Found: The requested resource could not be found, but it may be available again in the future.

Method Not Allowed: The client used an HTTP method other than POST.

Request timeout: The client took too long to transmit the request.

Requested uri is too long.

Unsupported Media Type.

Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.

An error occurred while processing the request. Please try again later. This can also indicate that the request reached an internal computation time threshold and timed out.

Internal network connectivity issue.

Service currently unavailable.

Internal network connectivity issue.

Service not found.

The request may return more than one route.
Each object has at least a summary field and a legs field. It may contain other fields depending on the request parameters.

The summary of a route, or of a route leg.
The summary object may be extended with new fields in the future; clients should ignore fields they do not recognize.

A description of a part of a route, comprised of an array of points.

• Contains the summary field and may contain the path field.

• Each additional waypoint provided in the request will result in an additional leg in the returned route.

The route geometry in GeoJSON format. Contains a type field set to LineString and a coordinates array where each element is a position on the surface of the globe defined as [longitude, latitude]. For more information, see the GeoJSON format section.

Example:

1
"path": {
2
  "type": "LineString",
3
  "coordinates": [
4
    [-73.9857, 40.7484],
5
    [-73.9851, 40.7496],
6
    [-73.9845, 40.7508]
7
  ]
8
}

This object is available inside route objects.

• It is a map where each key is a section type and each value is an array of section objects of that type.

• The structure of section objects is given below.

Index of the first coordinate (offset 0) in the route path this section applies to.

Index of the last coordinate (offset 0) in the route path this section applies to.

A 2-character ISO 3166-1 alpha-2 country code.

Type of the incident.

• Can currently be accident, brokenDownVehicle, dangerousConditions, flooding, fog, ice, jam, laneClosed, rain, roadClosed, roadWorks, wind, or unknown.

• See the tec field for detailed information.

The effective speed of the incident in km/h, averaged over its entire length.

The delay duration in seconds caused by the incident.

The magnitude of delay caused by the incident.
Possible values:

• unknown
• minor
• moderate
• major

• undefined, used for road closures and other indefinite delays

These values correspond to the values of the response field magnitudeOfDelay

Details of the traffic event. It uses the definitions in the TPEG2-TEC standard. It can contain the effectCode and causes fields.
A selection of TPEG2-TEC causes can be found in the Terms and definitions of Safety related message sets .

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.

Each object in the array describes one cause of the traffic event.

• It can contain the mainCauseCode and subCauseCode fields.

• It can be used to define iconography and descriptions.

The main cause of the traffic event. Contains a value in the tec002:CauseCode table, as defined in the TPEG2-TEC standard.
A selection of TPEG2-TEC causes can be found in the Terms and definitions of Safety related message sets .

The sub-cause of the traffic event. Contains a value in the sub cause table defined by the mainCauseCode, as defined in the TPEG2-TEC standard.
A selection of TPEG2-TEC causes can be found in the Terms and definitions of Safety related message sets .

A unique ID of the traffic incident.

The route or leg length in meters.

The estimated travel duration in seconds depending on traffic .

• If traffic has the value historical, then travelDurationInSeconds includes historical travel durations on the route.

• If traffic has the value live, then travelDurationInSeconds includes historical travel durations as well as traffic jams during the travel time window on the route.

The delay duration in seconds compared to free-flow conditions according to real-time traffic information. Note that this is zero if traffic has the value historical.

The portion of the route or leg, expressed in meters, that is affected by traffic events which cause the delay.

The distance (in meters) from the origin point of the 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.

The travel duration (in seconds) from the origin point of the 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 duration of the route.

• Included in all alternative (but not reference) route summary fields.

The coordinates of the first point following the origin point of the request where this route forks off from the reference route. The value is in GeoJSON format.

• 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.

Example:

1
"deviationPoint": {
2
  "type": "Point",
3
  "coordinates": [
4
    -73.9857,
5
    40.7484
6
  ]
7
}

For more details, see the GeoJSON format for deviation points section.

The estimated departure date and time for the route or leg. Specified as a dateTime.

The estimated arrival date and time for the route or leg. Specified as a dateTime.

• It always contains entries for the first and the last point in the route.

• For any pair of consecutive entries in the progressPoints array, progress for pathIndex values that are not explicitly present and are enclosed by said pair, can be linearly interpolated by summing up straight line distances of the leg points.

• The Haversine formula is precise enough to compute such distances.

A progress point object may contain the following members:

• pathIndex: index of the point (offset 0) in the route this object applies to.

• distanceInMeters: distance (in meters) from the start of the route to this point.

• travelDurationInSeconds: travel duration (in seconds) from the start of the route to this point.

The index of the waypoint at the end of the leg.
This index corresponds to the position of this waypoint in the list of waypoints in the routePlanningLocations POST data parameter in the request.
The first waypoint has an index equal to 0.
This field is not provided if the end of the leg corresponds to the destination.

Identifies the entry point that was used for the route at the end of the leg.
This index corresponds to the position of this entry point in the list of entry points within the respective leg.
The first entry point has an index equal to 0.
This field is only present if the leg had entryPoints in the request.

The key in the sections map identifies the section type. The possible keys are: carTrain, country, ferry, motorway, pedestrian, toll, traffic, travelMode, tunnel, carpool, urban, unpaved, lowEmissionZone, speedLimit.

• The country sections span between country border crossings, from the departure, or to the destination.

  • The section additionally contains countryCodeIso2 — the country code of the country in the ISO 3166-1 alpha-2 format.

  • If the route has disjointed parts in the same country, there will be several sections with the same countryCodeIso2.

  • 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 traffic section may additionally contain any of the following: iconCategory, effectiveSpeedInKilometersPerHour, delayDurationInSeconds, delayMagnitude, tec, eventId.

• travelMode sections cover the whole route. Each section’s travel mode is reported in travelMode .

• A speedLimit section additionally contains speedRestrictions list of objects.
  Each object in the speedRestrictions list contains type field (a string with value maximum) and inKilometersPerHour integer.

This field is either set to the value given to the POST data 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 travelMode.

This object provides a representation of the error message. It contains a code and a message field.