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

Route monitoring documentation

Table of contents

  • Creating route
  • Listing all client's routes
  • Get short data for a given route
  • Get detailed data for a given route
  • Edit existing route
  • Remove existing route
  • Route Statuses

 

Creating route

Response contains confirmation of requested data and assigned id of for a route.

Request

Request URL format

POST https://<baseURL>/routemonitoring/<versionNumber>/routes?key=<apiKey>

Request URL example

POST https://api.tomtom.com/routemonitoring/1/routes?key=<apiKey>

Request body example

{
  "name":"Test Route",
  "pathPoints":[
    {
      "latitude":51.76041,
      "longitude":19.47210
    },
    {
      "latitude":51.75959,
      "longitude":19.47312
    }
  ],
  "routedPathPoints":[
    {
      "latitude": 51.76041,
      "longitude": 19.4721
    },
    {
      "latitude": 51.76048,
      "longitude": 19.4727
    },
    {
      "latitude": 51.7603,
      "longitude": 19.47274
    },
    {
      "latitude": 51.7599,
      "longitude": 19.47283
    },
    {
      "latitude": 51.75957,
      "longitude": 19.47289
    },
    {
      "latitude": 51.75961,
      "longitude": 19.47312
    }
  ]
}

Request structure

Field Description Type / Values
name Name for newly created route String
pathPoints Start and end points 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 Detailed list of points creating route path. It can be obtained from TomTom's Routing API Two or more points as described above latitude, longitude pair

Response

Sample response

{
  "routeId":123,
  "routeName":"Test Route",
  "routeStatus":"NEW",
  "routeLength":161,
  "pathPoints":[
    {
      "latitude":51.76041,
      "longitude":19.4721
    },
    {
      "latitude":51.75959,
      "longitude":19.47312
    }
  ],
  "routedPathPoints":[
    {
      "latitude":51.76041,
      "longitude":19.4721
    },
    {
      "latitude":51.76048,
      "longitude":19.4727
    },
    {
      "latitude":51.7603,
      "longitude":19.47274
    },
    {
      "latitude":51.7599,
      "longitude":19.47283
    },
    {
      "latitude":51.75957,
      "longitude":19.47289
    },
    {
      "latitude":51.75961,
      "longitude":19.47312
    }
  ]
}

Response structure

Field Description
routeId Unique id of a route
routeName Confirmation of route name
routeStatus Status of this route (See: Route Statuses at the bottom of this page)
routeLength Calculated length of a route in meters
pathPoints Start and end points
routedPathPoints Detailed list of points creating route path

 

Listing all client's routes

Response contains array of all routes created with 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

Request URL format

GET https://<baseURL>/routemonitoring/<versionNumber>/routes?key=<apiKey>

Request URL example

GET https://api.tomtom.com/routemonitoring/1/routes?key=<apiKey>

Response

Sample response

[
  {
    "routeId": 123,
    "routeName": "Test Route",
    "routeStatus": "ACTIVE",
    "routePathPoints": [
      {
        "latitude": 51.76041,
        "longitude": 19.4721
      },
      {
        "latitude": 51.75959,
        "longitude": 19.47312
      }
    ],
    "travelTime": 19,
    "delayTime": 2,
    "passable": true,
    "routeLength": 161,
    "completeness": 89
  }
]

Response structure

Field Description
routeId Unique id of a route
routeName Confirmation of route name
routeStatus Status of this route (See: Route Statuses at the bottom of this page)
routePathPoints Start and end points
travelTime Current travel time in seconds
delayTime 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 Is route passable at given time?
routeLength Calculated length of a route in meters
completeness 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.

 

Get short data for a given route

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

Request

Request URL format

GET https://<baseURL>/routemonitoring/<versionNumber>/routes/{routeId}?key=<apiKey>

Request URL example

GET https://api.tomtom.com/routemonitoring/1/routes/123?key=<apiKey>

Response

Sample response

{
  "routeId": 123,
  "routeName": "Test Route",
  "routeStatus": "ACTIVE",
  "routePathPoints": [
    {
      "latitude": 51.76041,
      "longitude": 19.4721
    },
    {
      "latitude": 51.75959,
      "longitude": 19.47312
    }
  ],
  "travelTime": 19,
  "delayTime": 2,
  "passable": true,
  "routeLength": 161,
  "completeness": 89
}

Response structure

Field Description
routeId Unique id of a route
routeName Confirmation of route name
routeStatus Status of this route (See: Route Statuses at the bottom of this page)
routePathPoints Start and end points
travelTime Current travel time in seconds
delayTime 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 Is route passable at given time?
routeLength Calculated length of a route in meters
completeness 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.

 

Get detailed data for a given route

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

Request

Request URL format

GET https://<baseURL>/routemonitoring/<versionNumber>/routes/{routeId}/details?key=<apiKey>

Request URL example

GET https://api.tomtom.com/routemonitoring/1/routes/123/details?key=<apiKey>

Response

Sample response

{
  "routeId": 123,
  "routeName": "Test Route",
  "routeStatus": "ACTIVE",
  "routePathPoints": [
    {
      "latitude": 51.76041,
      "longitude": 19.4721
    },
    {
      "latitude": 51.75959,
      "longitude": 19.47312
    }
  ],
  "passable": true,
  "travelTime": 19,
  "delayTime": 2,
  "routeLength": 161,
  "completeness": 89,
  "routeConfidence": 63,
  "detailedSegments": [
    {
      "openLrId": "Cw3YMiTOpiKHDgTdAGEiFw==",
      "currentSpeed": 35,
      "relativeSpeed": 62,
      "confidence": 96,
      "openLrLength": 864,
      "coveredLength": 42,
      "shape": [
        {
          "latitude": 51.76041,
          "longitude": 19.4721
        },
        {
          "latitude": 51.76048,
          "longitude": 19.4727
        }
      ]
    },
    {
      "openLrId": "Cw3Y5iTOtjvvCABd/k07Hw==",
      "currentSpeed": 32,
      "relativeSpeed": 100,
      "confidence": 50,
      "openLrLength": 488,
      "coveredLength": 101,
      "shape": [
        {
          "latitude": 51.76048,
          "longitude": 19.4727
        },
        {
          "latitude": 51.76031,
          "longitude": 19.47275
        },
        {
          "latitude": 51.7599,
          "longitude": 19.47283
        },
        {
          "latitude": 51.75957,
          "longitude": 19.47289
        }
      ]
    },
    {
      "segmentId": 1186178939619212800,
      "averageSpeed": 20,
      "segmentLength": 17,
      "shape": [
        {
          "latitude": 51.75957,
          "longitude": 19.47289
        },
        {
          "latitude": 51.7596,
          "longitude": 19.47312
        },
        {
          "latitude": 51.75959,
          "longitude": 19.47312
        }
      ]
    }
  ]
}

Response structure

Field Description
routeId Unique id of a route
routeName Confirmation of route name
routeStatus Status of this route (See: Route Statuses at the bottom of this page)
routePathPoints Start and end points
travelTime Current travel time in seconds
delayTime 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 Is route passable at given time?
routeLength Calculated length of a route in meters
completeness 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.
routeConfidence 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.
detailedSegments Array of segments that make up a whole route and detailed information about current traffic on them
openLrId OpenLR code for segment
segmentId Segment id if OpenLR is not available
currentSpeed The current average speed at given segment (in kilometers per hour)
averageSpeed If current traffic is unavailable then average historical speed on given segment is presented (in kilometers per hour)
relativeSpeed Current speed presented as a percentage of the free flow speed - speed expected under ideal conditions (typically at night)
confidence 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.
openLrLength Length of a whole OpenLR segment described with given OpenLR id (in meters)
coveredLength Length of a OpenLR fragment that is actually covered with given route (in meters)
segmentLength If OpenLR is not available then only length of a segment is presented (in meters)
shape Detailed list of points that define given route fragment

 

Edit existing route

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

Request

Request URL format

PUT https://<baseURL>/routemonitoring/<versionNumber>/routes/{routeId}?key=<apiKey>

Request URL example

PUT https://api.tomtom.com/routemonitoring/1/routes/123?key=<apiKey>

 

Remove existing route

Response contains no data. Only correct status code is a confirmation.

Request

Request URL format

DELETE https://<baseURL>/routemonitoring/<versionNumber>/routes/{routeId}?key=<apiKey>

Request URL example

DELETE https://api.tomtom.com/routemonitoring/1/routes/123?key=<apiKey>

 

Route Statuses

Status Description
NEW New route was requested by user, 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 route definition was requested but route is not updated yet.
MM_FAILED Map matching failed for given path points; route can't be created. These routes should be deleted or updated with new geometry.
ARCHIVED Route was deleted and is not active anymore.