Service version: 2
Last edit: 2022.08.29

Purpose

The TomTom Route Monitoring API service provides an intuitive and powerful way to monitor strategic routes in real-time. Customers have the ability to pre-define routes important to their businesses getting detailed information on current travel time, current delay time and percentage delay, route distance, live data coverage, and data confidence level. The overall route information can also be checked on a segment level, providing accurate and detailed information of traffic flow dynamics down to short length extensions.

Confirm requested data and assigned ID

Returns a confirmation of requested data and the assigned id for a route.

Request data

HTTPS method: POST

  • Constants and parameters enclosed in curly brackets &#123 } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values.

Request URL format

https://{baseURL}/routemonitoring/{version}/routes?key={Your_API_Key}

Request URL example

https://api.tomtom.com/routemonitoring/2/routes?key={Your_API_Key}

Request curl example

curl -XPOST 'https://api.tomtom.com/routemonitoring/2/routes?key={Your_API_Key}'

POST body example

1{
2 "name": "Test Route",
3 "pathPoints": [
4 {
5 "latitude": 51.76041,
6 "longitude": 19.4721
7 },
8 {
9 "latitude": 51.76002,
10 "longitude": 19.47281
11 },
12 {
13 "latitude": 51.75961,
14 "longitude": 19.47312
15 }
16 ]
17}

Request parameters

Required parameters must be used or the call will fail. There are no optional parameters in this endpoint.

Required parameters

Description

baseURL
string

Base URL for calling TomTom services.


Value: api.tomtom.com

versionNumber
string

The version of the service to call.


Value: The current version is 2.

key
string

An API Key valid for the requested service.


Value: Your valid API Key.

POST request body fields

Field

Description

name
string

Name for a newly created route.

pathPoints
double

Two or more (start, end, and via) points describing a route. Without via points there is no guarantee that the route created using TomTom's Routing API is the route you want to measure.


Value: Latitude, longitude pair (in EPSG4326 projection), with the following constraints:

  • Latitude values must be in the range -90..+90 inclusive.
  • Longitude values must be in the range -180..+180 inclusive.

routedPathPoints
*double

Deprecated*

Deprecated
Note: Values from this field are ignored during route creation.

Response data

Example response

1{
2 "routeId": 123,
3 "routeName": "Test Route",
4 "routeStatus": "NEW",
5 "routeLength": 161,
6 "pathPoints": [
7 {
8 "latitude": 51.76041,
9 "longitude": 19.4721
10 },
11 {
12 "latitude": 51.76002,
13 "longitude": 19.47281
14 },
15 {
16 "latitude": 51.75959,
17 "longitude": 19.47312
18 }
19 ],
20 "routedPathPoints": [
21 {
22 "latitude": 51.76041,
23 "longitude": 19.4721
24 },
25 {
26 "latitude": 51.76048,
27 "longitude": 19.4727
28 },
29 {
30 "latitude": 51.7603,
31 "longitude": 19.47274
32 },
33 {
34 "latitude": 51.7599,
35 "longitude": 19.47283
36 },
37 {
38 "latitude": 51.75957,
39 "longitude": 19.47289
40 },
41 {
42 "latitude": 51.75961,
43 "longitude": 19.47312
44 }
45 ]
46}

Response fields

Field

Description

routeId
integer

Unique id of a route.

routeName
string

Confirmation of route name.

routeStatus
string

Status of this route (See: Route Statuses at the bottom of this page).

routeLength
integer

Calculated length of a route in meters.

pathPoints
array (of lat/lon)

Start and end points.

routedPathPoints
array (of lat/lon)

Deprecated.
Detailed list of points creating the route path.

Listing all of a client's routes

The response contains an array of all routes created with the given API Key and basic information about each of them. It excludes deleted routes (in ARCHIVED status - see: Route Statuses at the bottom of this page).

Request data

HTTPS method: GET

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values.

Request URL format

https://{baseURL}/routemonitoring/{version}/routes?key={Your_API_Key}

Request URL example

https://api.tomtom.com/routemonitoring/2/routes?key={Your_API_Key}

Request curl example

curl 'https://api.tomtom.com/routemonitoring/2/routes?key={Your_API_Key}'

Request parameters

Required parameters must be used or the call will fail. There are no optional parameters in this endpoint.

Required parameters

Description

baseURL
string

Base URL for calling TomTom services.


Value: api.tomtom.com

versionNumber
string

The version of the service to call.


Value: The current version is 2.

key
string

An API Key valid for the requested service.


Value: Your valid API Key.

Response data

Response example

1[
2 {
3 "routeId": 123,
4 "routeName": "Test Route",
5 "routeStatus": "ACTIVE",
6 "routePathPoints": [
7 {
8 "latitude": 51.76041,
9 "longitude": 19.4721
10 },
11 {
12 "latitude": 51.75959,
13 "longitude": 19.47312
14 }
15 ],
16 "travelTime": 19,
17 "typicalTravelTime": 19,
18 "delayTime": 2,
19 "passable": true,
20 "routeLength": 161,
21 "completeness": 89,
22 "typicalTravelTimeCoverage": 89
23 }
24]

Response fields

Field

Description

routeId
integer

Unique id of a route.

routeName
string

Confirmation of the route name.

routeStatus
string

Status of this route (See: Route Statuses at the bottom of this page).

routePathPoints
array (of lat/lon)

Start and end points.

travelTime
integer

Current travel time in seconds.

typicalTravelTime
integer

Typical travel time for the whole route at the given time based on TomTom Speed Profiles data. In case it is not available, the missing bits are replaced with current travel time when possible. When real time data is also not available, we use average historical travel time.

delayTime
integer

Traffic delay in seconds. It is the difference between the travel time calculated using all available traffic information and travel time calculated without the influence of current traffic

passable
boolean

Is route passable at given time?


If the route is impassable, then all values that summarize the entire route are calculated excluding closed section.

routeLength
integer

Calculated length of a route in meters.

completeness
integer

Percentage of a route that is covered with current traffic flow data. For some local roads current traffic can be unavailable and is not taken into account.

typicalTravelTimeCoverage
integer

Percentage of a route that is covered with Speed Profiles data used to calculate Typical Travel Time.

Get short data for a given route

The response contains basic information about the active route given in a request path. If the route is not in ACTIVE status, the response lacks traffic information (see: Route Statuses at the bottom of this page).

Request data

HTTPS method: GET

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values.

Request URL format

https://{baseURL}/routemonitoring/{version}/routes/{routeId}?key={Your_API_Key}

Request URL example

https://api.tomtom.com/routemonitoring/2/routes/123?key={Your_API_Key}

Request curl example

curl 'https://api.tomtom.com/routemonitoring/2/routes/123?key={Your_API_Key}'

Request parameters

Required parameters must be used or the call will fail. There are no optional parameters in this endpoint.

Required parameters

Description

baseURL
string

Base URL for calling TomTom services.


Value: api.tomtom.com

versionNumber
string

The version of the service to call.


Value: The current version is 2.

key
string

An API Key valid for the requested service.


Value: Your valid API Key.

routeId
integer

The route ID.


Value: Example: 123.

Response data

Response example

1{
2 "routeId": 123,
3 "routeName": "Test Route",
4 "routeStatus": "ACTIVE",
5 "routePathPoints": [
6 {
7 "latitude": 51.76041,
8 "longitude": 19.4721
9 },
10 {
11 "latitude": 51.75959,
12 "longitude": 19.47312
13 }
14 ],
15 "travelTime": 19,
16 "typicalTravelTime": 19,
17 "delayTime": 2,
18 "passable": true,
19 "routeLength": 161,
20 "completeness": 89,
21 "typicalTravelTimeCoverage": 89
22}

Response fields

Field

Description

routeId
integer

Unique id of a route.

routeName
string

Confirmation of route name.

routeStatus
string

Status of this route (See: Route Statuses at the bottom of this page).

routePathPoints
array (of lat/lon)

Start and end points.

travelTime
integer

Current travel time in seconds.

typicalTravelTime
integer

Typical travel time for the whole route at the given time based on TomTom Speed Profiles data. In case it is not available, the missing bits are replaced with current travel time when possible. When real time data is also not available, we use average historical travel time.

delayTime
integer

Traffic delay in seconds. It is the difference between the travel time calculated using all available traffic information and travel time calculated without the influence of current traffic.

passable
boolean

Is the route passable at the given time?


If the route is impassable, then all values that summarize the entire route are calculated excluding the closed section.

routeLength
integer

Calculated length of a route in meters.

completeness
integer

Percentage of route that is covered with current traffic flow data. For some local roads current traffic can be unavailable and is not taken into account.

typicalTravelTimeCoverage
integer

Percentage of route that is covered with Speed Profiles data used to calculate Typical Travel Time.

Get detailed data for a given route

The response contains detailed information about the active route given in the request path including data for individual segments. If OpenLR is not available for some local roads, then the data does not include current traffic information.

Request data

HTTPS method: GET

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values.

Request URL format

https://{baseURL}/routemonitoring/{version}/routes/{routeId}/details?key={Your_API_Key}

Request URL example

https://api.tomtom.com/routemonitoring/2/routes/123/details?key={Your_API_Key}

Request curl example

curl 'https://api.tomtom.com/routemonitoring/2/routes/123/details?key={Your_API_Key}'

Request parameters

Required parameters must be used or the call will fail. There are no optional parameters in this endpoint.

Required parameters

Description

baseURL
string

Base URL for calling TomTom services.


Value: api.tomtom.com

versionNumber
string

The version of the service to call.


Value: The current version is 2.

key
string

An API Key valid for the requested service.


Value: Your valid API Key.

routeId
integer

The route ID.


Value: Example: 123.

Response data

Response example - JSON

1{
2 "routeId": 123,
3 "routeName": "Test Route",
4 "routeStatus": "ACTIVE",
5 "routePathPoints": [
6 {
7 "latitude": 51.76041,
8 "longitude": 19.4721
9 },
10 {
11 "latitude": 51.75959,
12 "longitude": 19.47312
13 }
14 ],
15 "passable": true,
16 "travelTime": 19,
17 "delayTime": 2,
18 "typicalTravelTime": 19,
19 "routeLength": 161,
20 "completeness": 89,
21 "routeConfidence": 63,
22 "typicalTravelTimeCoverage": 89,
23 "detailedSegments": [
24 {
25 "openLrId": "Cw3YMiTOpiKHDgTdAGEiFw==",
26 "currentSpeed": 35,
27 "relativeSpeed": 62,
28 "typicalSpeed": 35,
29 "confidence": 96,
30 "openLrLength": 864,
31 "coveredLength": 42,
32 "shape": [
33 {
34 "latitude": 51.76041,
35 "longitude": 19.4721
36 },
37 {
38 "latitude": 51.76048,
39 "longitude": 19.4727
40 }
41 ]
42 },
43 {
44 "openLrId": "Cw3Y5iTOtjvvCABd/k07Hw==",
45 "currentSpeed": 32,
46 "relativeSpeed": 100,
47 "typicalSpeed": 32,
48 "confidence": 50,
49 "openLrLength": 488,
50 "coveredLength": 101,
51 "shape": [
52 {
53 "latitude": 51.76048,
54 "longitude": 19.4727
55 },
56 {
57 "latitude": 51.76031,
58 "longitude": 19.47275
59 },
60 {
61 "latitude": 51.7599,
62 "longitude": 19.47283
63 },
64 {
65 "latitude": 51.75957,
66 "longitude": 19.47289
67 }
68 ]
69 },
70 {
71 "segmentId": 1186178939619212800,
72 "averageSpeed": 20,
73 "segmentLength": 17,
74 "shape": [
75 {
76 "latitude": 51.75957,
77 "longitude": 19.47289
78 },
79 {
80 "latitude": 51.7596,
81 "longitude": 19.47312
82 },
83 {
84 "latitude": 51.75959,
85 "longitude": 19.47312
86 }
87 ]
88 }
89 ]
90}

Response fields

Field

Description

routeId
integer

Unique id of a route.

routeName
string

Confirmation of route name.

routeStatus
string

Status of this route (See: Route Statuses at the bottom of this page).

routePathPoints
array (of lat/lon)

Start and end points.

travelTime
integer

Current travel time in seconds.

delayTime
integer

Traffic delay in seconds. It is the difference between the travel time calculated using all available traffic information and travel time calculated without the influence of current traffic.

typicalTravelTime
integer

Typical travel time for the whole route at the given time based on TomTom Speed Profiles data. In case it is not available, the missing bits are replaced with current travel time when possible. When real time data is also not available, we use average historical travel time.

passable
boolean

Is the route passable at the given time?


If the route is impassable, then all values that summarize the entire route are calculated excluding the closed section.

routeLength
integer

Calculated length of a route in meters.

completeness
integer

Percentage of the route that is covered with current traffic flow data. For some local roads current traffic can be unavailable and is not taken into account.

routeConfidence
integer

Average confidence of current traffic data. The confidence is a measure of the quality of the provided travel time and speed. A value of 100 means full confidence, that the response contains the highest quality data. Lower values indicate the degree that the response may vary from the actual conditions on the road.

typicalTravelTimeCoverage
integer

Percentage of the route that is covered with Speed Profiles data used to calculate Typical Travel Time or Typical Speed.

detailedSegments
array

An array of segments that make up a whole route and detailed information about current traffic on it.

openLrId
string

OpenLR code for segment.

segmentId
integer

Segment id if OpenLR is not available.

currentSpeed
integer

The current average speed at given segment (in kilometers per hour).
When this part of the route is closed for traffic, then current speed equals 0.

averageSpeed
**

If current traffic is unavailable then the average historical speed on the given segment is presented (in kilometers per hour).

relativeSpeed
integer

Current speed presented as a percentage of the free flow speed. This is the speed expected under ideal conditions (typically at night).

typicalSpeed
integer

Typical speed at the given time based on TomTom Speed Profiles data.

confidence
integer

The confidence is a measure of the quality of the provided travel time and speed. A value of 100 means full confidence, and that the response contains the highest quality data. Lower values indicate the degree that the response may vary from the actual conditions on the road.

openLrLength
integer

Length of a whole OpenLR segment described with the given OpenLR id (in meters).

coveredLength
integer

Length of an OpenLR fragment that is actually covered with the given route (in meters).

segmentLength
integer

If OpenLR is not available then only the length of a segment is presented (in meters).

shape
array (of lat/lon)

Detailed list of points that define the given route fragment.

Edit existing route

The request path, request body, and response are identical as in route creation.

Request data

HTTPS method: PUT

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values.

Request URL format

https://{baseURL}/routemonitoring/{version}/routes/{routeId}?key={Your_API_Key}

Request URL example

https://api.tomtom.com/routemonitoring/2/routes/123?key={Your_API_Key}

Request curl example

curl -XPUT 'https://api.tomtom.com/routemonitoring/2/routes/123?key={Your_API_Key}'

Request parameters

Required parameters must be used or the call will fail. There are no optional parameters in this endpoint.

Required parameters

Description

baseURL
string

Base URL for calling TomTom services.


Value: api.tomtom.com

versionNumber
string

The version of the service to call.


Value: The current version is 2.

key
string

An API Key valid for the requested service.


Value: Your valid API Key.

routeId
integer

The route ID.


Value: Example: 123.

Remove existing route

The response contains no data. Only the correct status code is a confirmation.

Request data

HTTPS method: DELETE

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values.

Request URL format

https://{baseURL}/routemonitoring/{version}/routes/{routeId}?key={Your_API_Key}

Request URL example

https://api.tomtom.com/routemonitoring/2/routes/123?key={Your_API_Key}

Request curl example

curl -XDELETE 'https://api.tomtom.com/routemonitoring/2/routes/123?key={Your_API_Key}'

Request parameters

Required parameters must be used or the call will fail. There are no optional parameters in this endpoint.

Required parameters

Description

baseURL
string

Base URL for calling TomTom services.


Value: api.tomtom.com

versionNumber
string

The version of the service to call.


Value: The current version is 2.

key
string

An API Key valid for the requested service.


Value: Your valid API Key.

routeId
integer

The route ID.


Value: Example: 123.

Route Statuses

Status

Description

NEW

A new route was requested by the user; the route data is processed at the moment.

ACTIVE

Route is created and fully functional. Only routes in this status should be queried for travel times.

PENDING_UPDATE

Update to the route definition was requested but the route is not updated yet.

MM_FAILED

Map matching failed for the given path points; the route can't be created. These routes should be deleted or updated with new geometry.

ARCHIVED

Route was deleted and is not active anymore.