Service version: 1
Last edit: 2023.06.29

Purpose

The Traffic Stats API Area Analysis service calculates statistics for an area. 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 length of date range is 366 days.
  • The maximum number of time sets is 24.
  • Network size, calculated as the size of the convex hull of defined geometry, cannot be greater than 20 000 km².
  • 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/areaanalysis/{versionNumber}?key={Your_API_Key}

curl format

post
curl request format
curl -XPOST 'https://{baseURL}/traffic/trafficstats/areaanalysis/{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{
2 "jobName": "Test job",
3 "distanceUnit": "KILOMETERS",
4 "mapVersion": "2022.12",
5 "acceptMode": "AUTO",
6 "network": {
7 "name": "test",
8 "geometry": {
9 "type": "MultiPolygon",
10 "coordinates": [
11 [
12 [
13 [19.44305, 51.75612],
14 [19.44992, 51.75612],
15 [19.44992, 51.75947],
16 [19.44305, 51.75947],
17 [19.44305, 51.75612]
18 ]
19 ],
20 [
21 [
22 [19.45011, 51.75789],
23 [19.45687, 51.75789],
24 [19.45687, 51.75946],
25 [19.45011, 51.75946],
26 [19.45011, 51.75789]
27 ]
28 ]
29 ]
30 },
31 "timeZoneId": "Europe/Warsaw",
32 "frcs": ["0", "1", "2", "3", "4", "5", "6", "7"],
33 "probeSource": "ALL"
34 },
35 "dateRange": {
36 "name": "October 2022",
37 "from": "2022-10-01",
38 "to": "2022-10-31",
39 "exclusions": ["2022-10-06"]
40 },
41 "timeSets": [
42 {
43 "name": "Friday morning hour",
44 "timeGroups": [
45 {
46 "days": ["FRI"],
47 "times": ["7:00-8:00"]
48 }
49 ]
50 }
51 ]
52}

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

network
object

Network for calculations. See the Structure of network section.
Value: An object defining network.

dateRange
object

Range of dates for calculations. See the Structure of dateRange section.
Value: An object containing dates.

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 network, 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 network

Required parameters

Description

name
string

Name of the network.
Value: A network name.

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

frcs
array (of integers)

Functional road classes.
Value: A list of integers from range 0-8

geometry
object

Geometry of the network in GeoJSON format. Supported geometry types are Polygon and MultiPolygon. See RFC 7946.
Value: An object defining geometry.

Optional parameters

Description

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

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

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, geometry cannot be processed (it is effectively empty because there are no roads with selected frcs or it is defined 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 a year 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{
2 "summaries": [
3 {
4 "locationName": "test",
5 "dateRangeName": "October 2022",
6 "timeSetName": "Friday morning hour",
7 "averageSampleSize": 114.93,
8 "networkLength": 13.39,
9 "coveredNetworkLength": 9.83,
10 "distanceUnit": "KILOMETERS",
11 "frcDetails": [
12 {
13 "frc": 0,
14 "averageSampleSize": 0,
15 "networkLength": 0,
16 "coveredNetworkLength": 0,
17 "distanceUnit": "KILOMETERS"
18 },
19 {
20 "frc": 1,
21 "averageSampleSize": 0,
22 "networkLength": 0,
23 "coveredNetworkLength": 0,
24 "distanceUnit": "KILOMETERS"
25 },
26 {
27 "frc": 2,
28 "averageSampleSize": 0,
29 "networkLength": 0,
30 "coveredNetworkLength": 0,
31 "distanceUnit": "KILOMETERS"
32 },
33 {
34 "frc": 3,
35 "averageSampleSize": 414.64,
36 "networkLength": 2.23,
37 "coveredNetworkLength": 2.23,
38 "distanceUnit": "KILOMETERS"
39 },
40 {
41 "frc": 4,
42 "averageSampleSize": 127.22,
43 "networkLength": 3.16,
44 "coveredNetworkLength": 3.16,
45 "distanceUnit": "KILOMETERS"
46 },
47 {
48 "frc": 5,
49 "averageSampleSize": 94.22,
50 "networkLength": 0.79,
51 "coveredNetworkLength": 0.79,
52 "distanceUnit": "KILOMETERS"
53 },
54 {
55 "frc": 6,
56 "averageSampleSize": 33.15,
57 "networkLength": 1.22,
58 "coveredNetworkLength": 1.22,
59 "distanceUnit": "KILOMETERS"
60 },
61 {
62 "frc": 7,
63 "averageSampleSize": 8.13,
64 "networkLength": 5.98,
65 "coveredNetworkLength": 2.43,
66 "distanceUnit": "KILOMETERS"
67 }
68 ]
69 }
70 ]
71}

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{
2 "jobId": "{job_id}",
3 "jobState": "DONE",
4 "responseStatus": "OK",
5 "urls": [
6 "{url_for_json_result_file}",
7 "{url_for_geojson_result_file}",
8 "{url_for_shape_result_file}"
9 ]
10}

Results

Output of an Area Analysis is available in the following formats:

  • JSON
  • GeoJSON
  • SHAPE

JSON and GeoJSON results are provided in a gzip compressed format. 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 network.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.

network
object

Data for requested network.
Value: See the Structure of network section.

Structure of timeSets

Field(s)

Description

@id
integer

Helper reference for further use (in network.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 network

Field(s)

Description

networkName , zoneId ,
probeSource
string

From and as in the request.

mapsVersions
string

Version of maps used for map matching.

segmentResults
array

Data for each segment in given area. See the Structure of segmentResults section.

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