Route Analysis

Service version: 1

Last edit: 2023.06.29

Purpose

The Traffic Stats API Route Analysis service calculates the statistics for a defined route between an origin and a destination, optionally via waypoints. This service is asynchronous.

There are two endpoints consuming two types of requests. The first one is only for ordering jobs with POST requests. In its response the user receives a jobId, which should be used in the second endpoint with a GET request to the check job's status. When the job is successfully finished, the user will receive links in the response to download the results.

Using this service

There are some important notes about using this API service:

The latitude and longitude coordinates are in EPSG4326 / WGS84 format for both input and output. Other coordinate systems are not supported.
All averages are calculated arithmetically unless otherwise stated (example JSON field: harmonicAverageSpeed is calculated harmonically).
The current API version is 1.
The maximum route length is 200 kilometers. Routes longer than this will be rejected.
The maximum number of routes is 20.
The maximum number of unique days in all date ranges is 732.
The maximum length of date range is 366 days.
The maximum number of date ranges is 24.
The maximum number of time sets is 24.
When you define a route you should use it via points. Without via points there is no guarantee that the route that routing engine is using is the route you want to measure.
As the service is asynchronous it can take a while before results are available, depending on how busy the service is. Do not repost your request multiple times if you do not get feedback within seconds, we will ensure that the results are delivered.
At the same time you can have only 5 jobs in CALCULATIONS and SCHEDULED statuses per each developer key. When you reach this limit you can still create new jobs as they will be queued until at least one of currently running jobs is done.

Request data

HTTPS method: `POST`

Constants and parameters enclosed in curly brackets { } must be replaced with their values.

URL format

post

URL request format

https://{baseURL}/traffic/trafficstats/routeanalysis/{versionNumber}?key={Your_API_Key}

curl format

post

curl request format

curl -XPOST 'https://{baseURL}/traffic/trafficstats/routeanalysis/{versionNumber}?key={Your_API_Key}'

Required headers

Header	Value
Content-Type	`application/json`

Request parameters

The following table describes all of the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters may be used.

Required parameters	Description
`baseURL` string	Base URL for calling the API. Value: `api.tomtom.com`
`versionNumber` string	Service version number. Value: The current value is `1`.
`key` string	Authorization key for access to the API. Value: Your valid API Key.

Request POST body example - JSON

post
Request POST body - JSON
1{
"jobName": "Test job",
"distanceUnit": "KILOMETERS",
"mapVersion": "2022.12",
"acceptMode": "AUTO",
"routes": [
  {
    "name": "Some Route",
    "start": {
      "latitude": 51.7822,
      "longitude": 4.61689
    },
    "via": [
      {
        "latitude": 51.78153,
        "longitude": 4.60559
      }
    ],
    "end": {
      "latitude": 51.78555,
      "longitude": 4.61076
    },
    "fullTraversal": false,
    "zoneId": "Europe/Amsterdam",
    "probeSource": "ALL"
  }
],
"dateRanges": [
  {
    "name": "October 2022",
    "from": "2022-10-01",
    "to": "2022-10-31",
    "exclusions": ["2022-10-06"]
  }
],
"timeSets": [
  {
    "name": "Friday morning hour",
    "timeGroups": [
      {
        "days": ["FRI"],
        "times": ["7:00-8:00"]
      }
    ]
  }
]
47}

Request POST body parameters - JSON

The following JSON parameters refer to the POST request body.

Required parameters	Description
`jobName` string	Job name. Given for the user's convenience. Value: The job name.
`distanceUnit` string	Base unit used for distance and speed values. Values: KILOMETERS MILES
`routes` array	Routes for calculations. See the Structure of routes section. Value: An array containing routes.
`dateRanges` array	Ranges of dates for calculations. See the Structure of dateRanges section. Value: An array containing dateRanges.
`timeSets` array	Time sets for calculations. The first time set is a "Base Set" and every other time set will be compared to it in the output (example JSON field: travelTimeRatio). See the Structure of timeSets section. Value: An array containing timeSets.

Optional parameters	Description
`mapVersion` string	What map should be used. A list of currently available maps in all Traffic Stats API services can be checked at Available Maps. Value: Example: `2022.12` You can skip this parameter and we will pick map version for you based on selected date ranges in request.
`acceptMode` string	Defines whether the job should be accepted manually or automatically. Default value: `AUTO` Other value: `MANUAL`
`averageSampleSizeThreshold` integer	If the average sample size for any combination of route, date range, and time set will be lower than the given value, then the output will not be generated, and the job will be moved into the REJECTED state, and the user will not be charged for such report. If not specified, the output will always be generated no matter how many samples were available. Value: A sample size.

Structure of the route

Full archive support for this option is only offered for the last ~2 years of data (moving window). For older data, limited data are used which can impact your results.

Required parameters	Description
`name` string	Name of the route. Given for the user's convenience. Value: A route name.
`start` object	Point where the route starts `latitude` - Latitude of start point (required) `longitude` - Longitude of start point (required) Value: Longitude & latitude
`end` object	Point where the route ends `latitude` - Latitude of end point (required) `longitude` - Longitude of end point (required) Value: Longitude & latitude
`fullTraversal` boolean	When you only want vehicles that traversed the full route taken into account, you need to use this parameter. Values: `true` , `false`
`zoneId` string	In which time zone all times are given. Value: A time zone like: `Europe/Amsterdam` or `UTC`. See time zone names from the tz database for more.

Optional parameters	Description
`via` array	List of points through which the route should go. `latitude` - Latitude of start point (required) `longitude` - Longitude of start point (required) Value: List of objects: longitude & latitude
`probeSource` string	Determines from what devices data will be used. Default value: `PASSENGER` Possible values: `PASSENGER` - Passenger Vehicles `TELEMATICS` - Fleet Management Vehicles `ALL` - All Vehicles (Passenger and Fleet combined)

Optional parameters

Description

via
array

List of points through which the route should go.

latitude - Latitude of start point (required)
longitude - Longitude of start point (required)

Value: List of objects: longitude & latitude

probeSource
string

Determines from what devices data will be used.
Default value: PASSENGER
Possible values:

PASSENGER - Passenger Vehicles
TELEMATICS - Fleet Management Vehicles
ALL - All Vehicles (Passenger and Fleet combined)

Structure of dateRange

Required parameters	Description
`name` string	Date range name. Given for the user's convenience. Value: A date range name. For example: "Last working week of January".
`from` date	The date from (inclusive). Value: Date in the format: `YYYY-MM-DD`
`to` date	The date to (inclusive). Value: Date in the format: `YYYY-MM-DD`

Optional parameters	Description
`exclusions` array	List of days excluded from the date range. Value: List of dates in the format: `YYYY-MM-DD`.
`excludedDaysOfWeek` array	List of days of the week to be excluded. Values: `MON` `TUE` `WED` `THU` `FRI` `SAT` `SUN`

Optional parameters

Description

exclusions
array

List of days excluded from the date range.
Value: List of dates in the format: YYYY-MM-DD.

excludedDaysOfWeek
array

List of days of the week to be excluded.
Values:

MON
TUE
WED
THU
FRI
SAT
SUN

Structure of timeSets

Required parameters	Description
`name` string	Time set name. Value: Name given for the user's convenience.
`timeGroups` array	Time groups in the time set. Values: `days` - Days of week for the time group list of values: `MON` `TUE` `WED` `THU` `FRI` `SAT` `SUN` `times` - Time ranges for the time group, list of values in format: `HH:mm-HH:mm` (required).

Required parameters

Description

name
string

Time set name.
Value: Name given for the user's convenience.

timeGroups
array

Time groups in the time set.
Values:

days - Days of week for the time group list of values:
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
times - Time ranges for the time group, list of values in format: HH:mm-HH:mm (required).

Response data

In the response to the request a jobId is provided, which is required for further communication about the query. A JSON response content example:

Response body - JSON
1{
2  "jobId": "677",
3  "responseStatus": "OK",
4  "messages": ["Job created. Processing started."]
5}

Check job status

When a job has been initiated via the API request, it is possible to check the status.

Job status request

get

Job status URL request format

https://{baseURL}/traffic/trafficstats/status/{versionNumber}/{job_id}?key={Your_API_Key}

Job status request parameters

The below table describes all of the parameters that can be used in a request. Required parameters must be used or the call will fail. Optional parameters may be used.

Parameter	Description
`baseURL` string	Base URL for calling the API. Value: `api.tomtom.com`
`versionNumber` string	Service version number. Value: The current value is `1`.
`jobId` integer	The job ID. Value: Example: `123`
`key` string	Authorization key for access to the API. Value: Your valid API Key.

JSON response

Response body - JSON
1{
2  "jobId": "{job_id}",
3  "jobState": "{job_status}",
4  "responseStatus": "OK"
5}

Job status flow

During the process there are different stages applicable. Via the get state request you can see what the state of your job is. The following table shows the different stages of the process.

Status	Description
`NEW`	The job is waiting for scheduling.
`SCHEDULED`	Job is scheduled for calculations.
`MAPMATCHING`	Mapmatching is in progress.
`MAPMATCHED`	Mapmatching is done and the job is waiting for Geobase reading.
`READING_GEOBASE`	Geobase reading is in progress.
`CALCULATIONS`	Calculations are in progress.
`NEED_CONFIRMATION`	Occurs only if manual acceptance mode was used. The results are waiting to be accepted or rejected. In this state sample summaries for the job are provided when checking the job status.
`DONE`	Calculations are done. The results are waiting to be downloaded.
`ERROR`	The job stopped due to the fact that something went wrong. This can occur at any place in the flow.
`REJECTED`	The job is rejected. During processing it turned out that the job exceeds set limits, at least one of routes cannot be processed (route between points cannot be generated or is on area which is not supported), or there are less samples than required (see averageSampleSizeThreshold ). This can occur at any place in the flow.
`CANCELLED`	The job is cancelled. The owner of the job stopped processing it. It can be done at any time before the job is processed.
`EXPIRED`	The job is older than 2 years and all data has been removed.

Confirming job results

When the job's state is NEED_CONFIRMATION , then a summary URL will be available in the response.

Response body - JSON
1{
2  "jobId": "{job_id}",
3  "jobState": "NEED_CONFIRMATION",
4  "sampleDetailsUrl": "{url_for_sample_details_file}",
5  "responseStatus": "OK",
6  "messages": ["For more details see: {url_for_sample_details_file}"]
7}

A sample details file looks like this:

Sample details file - JSON
1{
"summaries": [
  {
    "locationName": "Some Route",
    "dateRangeName": "October 2022",
    "timeSetName": "Friday morning hour",
    "averageSampleSize": 150.93,
    "networkLength": 2.07,
    "coveredNetworkLength": 2.07,
    "distanceUnit": "KILOMETERS"
  }
]
13}

If you wish to accept the job, make the following request:

post

URL request example - accept the job

https://{baseURL}/traffic/trafficstats/status/{versionNumber}/{job_id}/accept?key={Your_API_Key}

Otherwise reject the job with the following request:

post

URL request example - reject the job

https://{baseURL}/traffic/trafficstats/status/{versionNumber}/{job_id}/reject?key={Your_API_Key}

Response data

Final DONE response

Response body - JSON
1{
"jobId": "{job_id}",
"jobState": "DONE",
"responseStatus": "OK",
"urls": [
  "{url_for_xlsx_result_file}",
  "{url_for_json_result_file}",
  "{url_for_geojson_result_file}",
  "{url_for_shape_result_file}"
]
11}

Results

Output of Route Analysis is available in the following formats:

XLSX
JSON
GeoJSON
SHAPE

JSON results are provided in a gzip compressed format. GeoJSON and SHAPE files are packed into zip archives. If you want to get an example of these files please click the applicable link in the preceding list.

JSON result description

Field(s)	Description
`jobName` string	From the request. Value: As in the request.
`creationTime` datetime	The job creation time. Value: Timestamp in the format: `yyyy-MM-ddTHH:mm:ss.SSSZ`
`userPreference` object	Requested preference. Value: `distanceUnit` as in the request.
`dateRanges` array	From the request Values: `@id` - Helper reference for further use (in routes.segmentResults.segmentTimeResults). `name, from, to, exclusions` - as in the request. `excludedDaysOfWeek` - as in the request, and a value from: `MONDAY` , `TUESDAY` , `WEDNESDAY` , `THURSDAY` , `FRIDAY` , `SATURDAY` , `SUNDAY`.
`timeSets` array	From the request. Value: See the Structure of timeSets section.
`routes` array	Data for each requested route. Value: See the Structure of routes section.

Structure of timeSets

Field(s)	Description
`@id` integer	Helper reference for further use (in routes.segmentResults.segmentTimeResults).
`name` string	From and as in the request.
`dayToTimeRanges` array	Time ranges from the request, grouped per day of the week: `dayOfWeek` - Day of the week for a time group, values from: `MONDAY` , `TUESDAY` , `WEDNESDAY` , `THURSDAY` , `FRIDAY` , `SATURDAY` , `SUNDAY`. `timeRanges` - Time ranges for a time group, a list of values in the format of: `HH:mm-HH:mm`.

Field(s)

Description

@id
integer

Helper reference for further use (in routes.segmentResults.segmentTimeResults).

name
string

From and as in the request.

dayToTimeRanges
array

Time ranges from the request, grouped per day of the week:

dayOfWeek - Day of the week for a time group, values from: MONDAY , TUESDAY , WEDNESDAY , THURSDAY , FRIDAY , SATURDAY , SUNDAY.
timeRanges - Time ranges for a time group, a list of values in the format of: HH:mm-HH:mm.

Structure of routes

Field(s)	Description
`routeName` , `zoneId` , `probeSource` string	From and as in the request.
`fullTraversal` boolean	From and as in the request.
`mapsVersions` string	Version of maps used for map matching.
`segmentResults` array	Data for each segment in given route. See Structure of segmentResults.
`summaries` array	Summary reports for each calculated date range-time set pair for the whole route. See Structure of summaries.

Structure of segmentResults

Field(s)	Description
`segmentId` long	Depending on the map on which job is processed it can be a MultiNet Segment ID (optionally prefixed by `-` and in such case there could be two segmentId's in the results whose presence indicates both directions: the negative value and the positive value) or a long numeric value.
`newSegmentId` string	Depending on the map on which job is processed it can be a MultiNet-R Segment ID (optionally prefixed by `-` and in such case there could be two newSegmentId's in the results whose presence indicates both directions: one prefixed by `-` and the other not prefixed) or a stringified numeric value.
`speedLimit` integer	Speed limit (in kmph or mph according to `userPreference` ).
`frc` integer (0-8)	Functional Road Class.
`streetName` string	The street name.
`distance` float	The length of a segment (in meters or feet according to `userPreference` ).
`shape` array	Geometrical shape of a segment. A list of pairs: longitude & latitude.
`segmentTimeResults` array	See the Structure of segmentTimeResults section.

Structure of segmentTimeResults

Field	Description
`timeSet` integer	Reference to `TimeSet` in which calculations were made.
`dateRange` integer	Reference to `DateRange` in which calculations were made.
`harmonicAverageSpeed` float	Harmonic average speed (in kmph or mph according to `userPreference` ).
`medianSpeed` float	Median speed (in kmph or mph according to `userPreference` ).
`averageSpeed` float	Average speed (in kmph or mph according to `userPreference` ).
`standardDeviationSpeed` float	Standard deviation of speed (in kmph or mph according to `userPreference` ).
`travelTimeStandardDeviation` float	Standard deviation of travel time (in seconds).
`sampleSize` integer	The sample size visible on the segment. These are unique vehicles traveling on segment. If several measurements are received from the same vehicle on a single segment it is only counted once in the sample size count.
`averageTravelTime` float	Average travel time (in seconds).
`medianTravelTime` float	Median travel time (in seconds).
`travelTimeRatio` float	Ratio of travel time in the current `TimeSet` to travel time in the Base Set (first `TimeSet` and same `DateRange` ).
`speedPercentiles` array (of 19 integers)	Percentile speeds in ascending order: 5th, 10th, ... 90th, 95th (in kmph or mph according to `userPreference`).

Structure of summaries

Field	Description
`dateRange` integer	Reference to `DateRange` in which calculations were made.
`timeSet` integer	Reference to `TimeSet` in which calculations were made.
`distance` float	The length of whole route (in meters or feet according to `userPreference`).
`coveredDistance` float	Summary length of segments covered with data (as above).
`averageSampleSize` float	The total sample size divided by the amount of segments. These are unique vehicles traveling on each segment in each time period. If several measurements are received from the same vehicle on a single segment it is only counted once in the sample size count.
`harmonicAverageSpeed` float	Harmonic average speed for the covered part of route.
`averageTravelTime` float	Average travel time for the covered part of route.
`medianTravelTime` float	Median travel time for the covered part of route.
`travelTimeStandardDeviation` float	Travel time standard deviation (in seconds). Only for full traversal routes.
`averageTravelTimeRatio` float	Ratio of average travel time in the current `TimeSet` to average travel time in the Base Set (first `TimeSet` and same `DateRange`).
`planningTimeIndex` float	Ratio of 95th travel time percentile in the current `TimeSet` to average travel time in the Base Set (first `TimeSet` and same `DateRange`).
`travelTimePercentiles` array (of 19 Floats)	Percentile travel time in ascending order: 5th, 10th, ... 90th, 95th (in seconds).
`speedPercentiles` array (of 19 Floats)	Percentile speeds in ascending order: 5th, 10th, ... 90th, 95th (in kmph or mph according to `userPreference`)

Route Analysis

Purpose

Using this service

Request data

HTTPS method: POST

URL format

curl format

Required headers

Request parameters

Request POST body example - JSON

Request POST body parameters - JSON

Structure of the route

Structure of dateRange

Structure of timeSets

Response data

Check job status

Job status request

Job status request parameters

JSON response

Job status flow

Confirming job results

Response data

Final DONE response

Results

JSON result description

Structure of timeSets

Structure of routes

Structure of segmentResults

Structure of segmentTimeResults

Structure of summaries

HTTPS method: `POST`