Route Monitoring

Service version: 2
Last edit: 2022.07.25

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 example
https://{baseURL}/routemonitoring/{version}/routes?key={apiKey}

Request URL example

POST
URL request example
https://api.tomtom.com/routemonitoring/2/routes?key={apiKey}

POST body example

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}

POST body fields

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

Request parameters

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

Required parametersDescription
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

Sample response

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

FieldDescription
routeIdUnique id of a route.
routeNameConfirmation of route name.
routeStatusStatus of this route (See: Route Statuses at the bottom of this page).
routeLengthCalculated length of a route in meters.
pathPointsStart and end points.
routedPathPointsDeprecated.
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 example
https://{baseURL}/routemonitoring/{version}/routes?key={apiKey}

Request URL example

GET
URL request example
https://api.tomtom.com/routemonitoring/2/routes?key={apiKey}

Request parameters

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

Required parametersDescription
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

Sample response

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

FieldDescription
routeIdUnique id of a route.
routeNameConfirmation of the route name.
routeStatusStatus of this route (See: Route Statuses at the bottom of this page).
routePathPointsStart and end points.
travelTimeCurrent travel time in seconds.
typicalTravelTimeTypical 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.
delayTimeTraffic 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
passableIs route passable at given time?
If the route is impassable, then all values that summarize the entire route are calculated excluding closed section.
routeLengthCalculated length of a route in meters.
completenessPercentage 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.
typicalTravelTimeCoveragePercentage 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={apiKey}

Request URL example

GET
URL request example
https://api.tomtom.com/routemonitoring/2/routes/123?key={apiKey}

Request parameters

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

Required parametersDescription
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

Sample response

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

FieldDescription
routeIdUnique id of a route.
routeNameConfirmation of route name.
routeStatusStatus of this route (See: Route Statuses at the bottom of this page).
routePathPointsStart and end points.
travelTimeCurrent travel time in seconds.
typicalTravelTimeTypical 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.
delayTimeTraffic 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.
passableIs 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.
routeLengthCalculated length of a route in meters.
completenessPercentage 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.
typicalTravelTimeCoveragePercentage 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 example
https://{baseURL}/routemonitoring/{version}/routes/{routeId}/details?key={apiKey}

Request URL example

GET
URL request example
https://api.tomtom.com/routemonitoring/2/routes/123/details?key={apiKey}

Request parameters

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

Required parametersDescription
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

Sample response

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

FieldDescription
routeIdUnique id of a route.
routeNameConfirmation of route name.
routeStatusStatus of this route (See: Route Statuses at the bottom of this page).
routePathPointsStart and end points.
travelTimeCurrent travel time in seconds.
delayTimeTraffic 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.
typicalTravelTimeTypical 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.
passableIs 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.
routeLengthCalculated length of a route in meters.
completenessPercentage 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.
routeConfidenceAverage 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.
typicalTravelTimeCoveragePercentage of the route that is covered with Speed Profiles data used to calculate Typical Travel Time or Typical Speed.
detailedSegmentsAn array of segments that make up a whole route and detailed information about current traffic on it.
openLrIdOpenLR code for segment.
segmentIdSegment id if OpenLR is not available.
currentSpeedThe current average speed at given segment (in kilometers per hour).
averageSpeedIf current traffic is unavailable then the verage historical speed on the given segment is presented (in kilometers per hour).
relativeSpeedCurrent speed presented as a percentage of the free flow speed. This is the speed expected under ideal conditions (typically at night).
typicalSpeedTypical speed at the given time based on TomTom Speed Profiles data.
confidenceThe 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.
openLrLengthLength of a whole OpenLR segment described with the given OpenLR id (in meters).
coveredLengthLength of an OpenLR fragment that is actually covered with the given route (in meters).
segmentLengthIf OpenLR is not available then only the length of a segment is presented (in meters).
shapeDetailed 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 example
https://{baseURL}/routemonitoring/{version}/routes/{routeId}?key={apiKey}

Request URL example

PUT
URL request example
https://api.tomtom.com/routemonitoring/2/routes/123?key={apiKey}

Request parameters

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

Required parametersDescription
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

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

Request URL example

DELETE
URL request example
https://api.tomtom.com/routemonitoring/2/routes/123?key={apiKey}

Request parameters

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

Required parametersDescription
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

StatusDescription
NEWA new route was requested by the user; the route data is processed at the moment.
ACTIVERoute is created and fully functional. Only routes in this status should be queried for travel times.
PENDING_UPDATEUpdate to the route definition was requested but the route is not updated yet.
MM_FAILEDMap matching failed for the given path points; the route can't be created. These routes should be deleted or updated with new geometry.
ARCHIVEDRoute was deleted and is not active anymore.