Developer

Route Monitoring

Request Access
Service version: 3
Last edit: 2023.10.31

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 { } 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

post
URL request format
https://{baseURL}/routemonitoring/{version}/routes?key={Your_API_Key}

Request URL example

post
URL request example
https://api.tomtom.com/routemonitoring/3/routes?key={Your_API_Key}

Request curl example

post
URL request example
curl -XPOST 'https://api.tomtom.com/routemonitoring/3/routes?key={Your_API_Key}'

POST body example

post
POST request body - JSON
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 3.

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 internal routing is the route you want to measure. Use the preview endpoint to check route geometry before creation.


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

post
Response body example - JSON
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

get
URL request format
https://{baseURL}/routemonitoring/{version}/routes?key={Your_API_Key}

Request URL example

get
URL request example
https://api.tomtom.com/routemonitoring/3/routes?key={Your_API_Key}

Request curl example

get
curl request example
curl 'https://api.tomtom.com/routemonitoring/3/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 3.

key
string

An API Key valid for the requested service.


Value: Your valid API Key.

Response data

Response example

Response body example - JSON
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

get
URL request example
https://{baseURL}/routemonitoring/{version}/routes/{routeId}?key={Your_API_Key}

Request URL example

get
URL request example
https://api.tomtom.com/routemonitoring/3/routes/123?key={Your_API_Key}

Request curl example

get
curl request example
curl 'https://api.tomtom.com/routemonitoring/3/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 3.

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

Response body 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  "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

get
URL request format
https://{baseURL}/routemonitoring/{version}/routes/{routeId}/details?key={Your_API_Key}

Request URL example

get
URL request example
https://api.tomtom.com/routemonitoring/3/routes/123/details?key={Your_API_Key}

Request curl example

get
curl request example
curl 'https://api.tomtom.com/routemonitoring/3/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 3.

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

Response body example - JSON
1{
2  "routeId": 1,
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  "routeLength": 151,
17  "travelTime": 21,
18  "delayTime": 5,
19  "typicalTravelTime": 20,
20  "completeness": 91,
21  "routeConfidence": 82,
22  "typicalTravelTimeCoverage": 100,
23  "detailedSegments": [
24    {
25      "segmentId": 1186178914586853376,
26      "segmentIdStr": "1186178914586853376",
27      "averageSpeed": 55,
28      "typicalSpeed": 51,
29      "segmentLength": 26,
30      "openLrId": "Cw3YMiTOphpnBAF5ACEaFw==",
31      "currentSpeed": 57,
32      "relativeSpeed": 98,
33      "confidence": 100,
34      "openLrLength": 262,
35      "shape": [
36        {
37          "latitude": 51.76041,
38          "longitude": 19.4721
39        },
40        {
41          "latitude": 51.76045,
42          "longitude": 19.47247
43        }
44      ]
45    },
46    {
47      "segmentId": 1186178914586755072,
48      "segmentIdStr": "1186178914586755072",
49      "averageSpeed": 54,
50      "typicalSpeed": 51,
51      "segmentLength": 9,
52      "openLrId": "Cw3YMiTOphpnBAF5ACEaFw==",
53      "currentSpeed": 57,
54      "relativeSpeed": 98,
55      "confidence": 100,
56      "openLrLength": 262,
57      "shape": [
58        {
59          "latitude": 51.76045,
60          "longitude": 19.47247
61        },
62        {
63          "latitude": 51.76046,
64          "longitude": 19.4726
65        }
66      ]
67    },
68    {
69      "segmentId": 1186178913858912256,
70      "segmentIdStr": "1186178913858912256",
71      "averageSpeed": 26,
72      "typicalSpeed": 26,
73      "segmentLength": 25,
74      "openLrId": "Cw3Y4STOtTvtCABn/k87Hw==",
75      "currentSpeed": 23,
76      "relativeSpeed": 71,
77      "confidence": 76,
78      "openLrLength": 488,
79      "shape": [
80        {
81          "latitude": 51.76046,
82          "longitude": 19.4726
83        },
84        {
85          "latitude": 51.76026,
86          "longitude": 19.47277
87        }
88      ]
89    },
90    {
91      "segmentId": 1186178914150940672,
92      "segmentIdStr": "1186178914150940672",
93      "averageSpeed": 26,
94      "typicalSpeed": 25,
95      "segmentLength": 40,
96      "openLrId": "Cw3Y4STOtTvtCABn/k87Hw==",
97      "currentSpeed": 23,
98      "relativeSpeed": 71,
99      "confidence": 76,
100      "openLrLength": 488,
101      "shape": [
102        {
103          "latitude": 51.76026,
104          "longitude": 19.47277
105        },
106        {
107          "latitude": 51.7599,
108          "longitude": 19.47283
109        }
110      ]
111    },
112    {
113      "segmentId": 1186178914151202816,
114      "segmentIdStr": "1186178914151202816",
115      "averageSpeed": 25,
116      "typicalSpeed": 24,
117      "segmentLength": 37,
118      "openLrId": "Cw3Y4STOtTvtCABn/k87Hw==",
119      "currentSpeed": 23,
120      "relativeSpeed": 71,
121      "confidence": 76,
122      "openLrLength": 488,
123      "shape": [
124        {
125          "latitude": 51.7599,
126          "longitude": 19.47283
127        },
128        {
129          "latitude": 51.75957,
130          "longitude": 19.47289
131        }
132      ]
133    },
134    {
135      "segmentId": 1186178913858781184,
136      "segmentIdStr": "1186178913858781184",
137      "averageSpeed": 20,
138      "typicalSpeed": 19,
139      "segmentLength": 14,
140      "shape": [
141        {
142          "latitude": 51.75957,
143          "longitude": 19.47289
144        },
145        {
146          "latitude": 51.7596,
147          "longitude": 19.47309
148        }
149      ]
150    }
151  ]
152}

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.

segmentId
integer

Segment id.

segmentIdStr
string

String representation of the segmentId field. Can be used to avoid JavaScript parsing problems on frontend applications.

averageSpeed
**

The average historical speed on the given segment (in kilometers per hour).

typicalSpeed
integer

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

segmentLength
integer

The length of a segment (in meters).

openLrId
string

OpenLR code for segment if 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.

relativeSpeed
integer

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

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

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

put
URL request format
https://{baseURL}/routemonitoring/{version}/routes/{routeId}?key={Your_API_Key}

Request URL example

put
URL request example
https://api.tomtom.com/routemonitoring/3/routes/123?key={Your_API_Key}

Request curl example

put
curl request example
curl -XPUT 'https://api.tomtom.com/routemonitoring/3/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 3.

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

delete
URL request format
https://{baseURL}/routemonitoring/{version}/routes/{routeId}?key={Your_API_Key}

Request URL example

delete
URL request example
https://api.tomtom.com/routemonitoring/3/routes/123?key={Your_API_Key}

Request curl example

delete
curl request example
curl -XDELETE 'https://api.tomtom.com/routemonitoring/3/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 3.

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.

Get route preview

The response contains the geometry of a route which can be created for given path points.

Request data

HTTPS method: POST

  • 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

post
URL request format
https://{baseURL}/routemonitoring/{version}/routing?key={Your_API_Key}

Request URL example

post
URL request example
https://api.tomtom.com/routemonitoring/3/routing?key={Your_API_Key}

Request curl example

post
URL request example
curl -XPOST 'https://api.tomtom.com/routemonitoring/3/routing?key={Your_API_Key}'

POST body example

post
POST request body - JSON
1{
2  "pathPoints": [
3    {
4      "latitude": 51.73253,
5      "longitude": 19.36712
6    },
7    {
8      "latitude": 51.73601,
9      "longitude": 19.36572
10    }
11  ]
12}

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

key
string

An API Key valid for the requested service.


Value: Your valid API Key.

POST request body fields

Field

Description

pathPoints
double

Two or more (start, end, and via) points describing a route.


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.

Response data

Example response

post
Response body example - JSON
1{
2  "route": [
3    {
4      "latitude": 51.73252,
5      "longitude": 19.36712
6    },
7    {
8      "latitude": 51.73423,
9      "longitude": 19.36647
10    },
11    {
12      "latitude": 51.73601,
13      "longitude": 19.36573
14    }
15  ],
16  "length": 400,
17  "mapVersion": "2023.06.006",
18  "segments": [
19    "1186178914044641281"
20  ]
21}

Response fields

Field

Description

route
array (of lat/lon)

Detailed list of points creating the route path.

length
integer

Calculated length of a route in meters.

mapVersion
integer

Map version used to generate route.

segments
array (of strings)

List of map segments used to prepare route.