Traffic Density

Service version: 1
Last edit: 2022.07.23

Purpose

The Traffic Density service gives insight to the amount of data available 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 in response will receive links to download results.

Using this service

There are some important notes about using this service:

  • The latitude and longitude coordinates are in EPSG4326 / WGS84 format for both input and output. Other coordinate systems are not supported.
  • 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 size of bounding box 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 example
https://{baseURL}/traffic/trafficstats/trafficdensity/{versionNumber}?key={apiKey}

Required headers

HeaderValue

Content-Type

application/json

Request Parameters

The table below 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.

ParameterDescriptionReq'd?Type / ValuesDefault Value
baseURLBase URL for calling the API.Yesapi.tomtom.com
versionNumberService version number. The current value is 1.Yes1
apiKeyAuthorization key for access to the API.YesAPI Key

JSON request parameters

The following JSON parameters refer to the POST request.

ParameterDescriptionReq'd?Type / ValuesDefault Value
jobNameJob name. Given for the user's convenience.YesString
distanceUnitBase unit used for distance and speed.Yes
  • KILOMETERS
  • MILES
mapVersionWhat map should be used. List of currently available maps in all Traffic Stats API services can be checked at Available Maps.NoString2016.12
acceptModeDefines whether the job should be accepted manually or automatically.No
  • AUTO
  • MANUAL
AUTO
averageSampleSizeThresholdIf 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 user will not be charged for such report. If not specified the output will be always generated no matter how many samples were available.NoInteger
networkNetwork for calculations. See the Structure of network section.YesObject
dateRangeRange of dates for calculations. See the Structure of dateRange section.YesObject
timeSetsTime sets for calculations. See the Structure of timeSets section.YesList

Structure of network

ParameterDescriptionReq'd?Type / ValuesDefault Value
nameName of the network.YesString
timeZoneIdIn which time zone all times are given.YesString
Time zone like: "Europe/Amsterdam" or "UTC". See time zone names from tz database for more.
frcsFunctional road classes.YesList of Integers from range 0-8
probeSourceDetermines from what devices data will be used.
Possible values:
  • PASSENGER - Passenger Vehicles
  • TELEMATICS - Fleet Management Vehicles
  • ALL - All Vehicles (Passenger and Fleet combined)
NoString
ALL, PASSENGER, TELEMATICS
PASSENGER
geometryGeometry of the network in GeoJSON format. Supported geometry types are Polygon and MultiPolygon. See RFC 7946.YesObject
boundingBoxBounding box of the network. Mutually exclusive with geometry. Deprecated, please use geometry.NoObject

Structure of dateRange

ParameterDescriptionReq'd?Type / ValuesDefault Value
nameDate range name. Given for the user's convenience.YesString
fromDate from (inclusive).YesDate in format: YYYY-MM-DD
toDate to (inclusive).YesDate in format: YYYY-MM-DD.
exclusionsList of days excluded from date range.NoList of dates in format: YYYY-MM-DD.
excludedDaysOfWeekList of days of week to be excluded.No

List of values:

  • MON
  • TUE
  • WED
  • THU
  • FRI
  • SAT
  • SUN

Structure of timeSets

ParameterDescriptionReq'd?Type / ValuesDefault Value
nameTime set name. Given for the user's convenience.YesString
timeGroupsTime groups in time set
  • days - Days of week for the time group list of values:
    • MON
    • TUE
    • WED
    • THU
    • FRI
    • SAT
    • SUN
  • times - Time ranges for time group, list of values in format: HH:mm-HH:mm (required).
YesList

JSON example request

POST
Request body - JSON
1{
2 "jobName":"Test job",
3 "distanceUnit":"KILOMETERS",
4 "mapVersion" : "2020.09",
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": [
33 "0",
34 "1",
35 "2",
36 "3",
37 "4",
38 "5",
39 "6",
40 "7",
41 "8"
42 ],
43 "probeSource":"ALL"
44},
45 "dateRange":
46 {
47 "name":"Last working week of January",
48 "from":"2021-01-25",
49 "to":"2021-01-29",
50 "exclusions":[
51 "2021-01-26",
52 "2021-01-27"
53 ]
54 },
55 "timeSets":[
56 {
57 "name":"Monday morning hour",
58 "timeGroups":[
59 {
60 "days":[
61 "MON"
62 ],
63 "times":[
64 "7:00-8:00"
65 ]
66 }
67 ]
68 }
69 ]
70}

Response data

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

POST
Response body - JSON
{"jobId":"677","responseStatus":"OK","messages":["Job created. Processing started."]}

Check job status

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

JSON request

GET
Job status URL request example
https://{baseURL}/traffic/trafficstats/status/{versionNumber>/{job_id}?key={apiKey}

Job status parameters

The table below 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.

ParameterDescriptionReq'd?Type / ValuesDefault Value
baseURLBase URL for calling the API.Yesapi.tomtom.com
versionNumberService version number. The current value is 1.Yes1
apiKeyAuthorization key for access to the API.YesAPI Key

JSON response

GET
Response body - JSON
{"jobId":"{job_id}","jobState":"{job_status}","responseStatus":"OK"}

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.

StatusDescription
NEWThe job is waiting for mapmatching to start.
SCHEDULEDJob is scheduled for calculations.
MAPMATCHINGMapmatching is in progress.
MAPMATCHEDMapmatching is done and the job is waiting for Geobase reading.
READING_GEOBASEGeobase reading is in progress.
CALCULATIONSCalculations are in progress.
NEED_CONFIRMATIONOccurs 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 job status.
DONECalculations are done. The results are waiting to be downloaded.
ERRORThe job stopped due to the fact that something went wrong. This can occur at any place in the flow.
REJECTEDThe job is rejected. During processing it turned out that the job exceeds set limits, bounding box 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.
CANCELLEDThe job is cancelled. The owner of the job stopped processing it. It can be done at any time before the job is processed.
EXPIREDThe 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.

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

Sample details file looks like this:

1{
2 "summaries": [
3 {
4 "locationName": "test",
5 "dateRangeName": "Last working week of January",
6 "timeSetName": "Monday morning hour",
7 "averageSampleSize": 17.06,
8 "frcDetails": [
9 {
10 "frc": 0,
11 "averageSampleSize": 0.0,
12 "networkLength": 0.0,
13 "distanceUnit": "KILOMETERS"
14 },
15 {
16 "frc": 1,
17 "averageSampleSize": 0.0,
18 "networkLength": 0.0,
19 "distanceUnit": "KILOMETERS"
20 },
21 {
22 "frc": 2,
23 "averageSampleSize": 0.0,
24 "networkLength": 0.0,
25 "distanceUnit": "KILOMETERS"
26 },
27 {
28 "frc": 3,
29 "averageSampleSize": 0.0,
30 "networkLength": 0.0,
31 "distanceUnit": "KILOMETERS"
32 },
33 {
34 "frc": 4,
35 "averageSampleSize": 30.08,
36 "networkLength": 5.41,
37 "distanceUnit": "KILOMETERS"
38 },
39 {
40 "frc": 5,
41 "averageSampleSize": 11.96,
42 "networkLength": 0.78,
43 "distanceUnit": "KILOMETERS"
44 },
45 {
46 "frc": 6,
47 "averageSampleSize": 5.63,
48 "networkLength": 1.22,
49 "distanceUnit": "KILOMETERS"
50 },
51 {
52 "frc": 7,
53 "averageSampleSize": 0.77,
54 "networkLength": 4.55,
55 "distanceUnit": "KILOMETERS"
56 },
57 {
58 "frc": 8,
59 "averageSampleSize": 0.0,
60 "networkLength": 0.0,
61 "distanceUnit": "KILOMETERS"
62 }
63 ]
64 }
65 ]
66}

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

POST
URL request example
https://{baseURL}/traffic/trafficstats/status/{versionNumber}/{job_id}/accept?key={apiKey}

Otherwise reject the job with the following request:

POST
URL request example
https://{baseURL}/traffic/trafficstats/status/{versionNumber}/{job_id}/reject?key={apiKey}

Response and Results

Final DONE response

{"jobId":"{job_id}","jobState":"DONE","responseStatus":"OK","urls":["{url_for_json_result_file}","{url_for_geojson_result_file}","{url_for_shape_result_file}"]}

Results

Output of Traffic Density is available in JSON , GeoJSON and SHAPE format. 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 on the applicable names.

JSON result description

Field(s)DescriptionType / Values
jobName(from request)(as in request)
creationTimeJob creation time.Timestamp in the format:yyyy-MM-ddTHH:mm:ss.SSSZ
userPreferenceRequested preference
  • distanceUnit - (as in request)
Object
dateRanges(from request)
  • @id - Helper reference for further use (in network.segmentResults.segmentProbeCounts).
  • name, from, to, exclusions - as in request.
  • excludedDaysOfWeek - as in request, value from: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
List
timeSets(from request) See the Structure of timeSets section.List
networkData for requested network. See the Structure of network section.Object

Structure of timeSets

Field(s)DescriptionType / Values
@idHelper reference for further use (in network.segmentResults.segmentProbeCounts).Integer
name(from request)(as in request)
dayToTimeRangesTime ranges from request grouped per day of week:
  • dayOfWeek - Day of week for time group, value from: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
  • timeRanges - Time ranges for time group, list of values in format: HH:mm-HH:mm.
List

Structure of network

Field(s)DescriptionType / Values
networkName, zoneId, probeSource(from request)(as in request)
mapsVersionsVersion of maps used for map matching.String
segmentResultsData for each segment in given area. See the segmentResults section.

Structure of segmentResults

Field(s)DescriptionType / Values
segmentIdDepending 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.Long
newSegmentIdDepending 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 other not) or stringified numeric value.String
speedLimitSpeed limit (in kmph or mph according to userPreference).Integer
frcFunctional Road Class.Integer (0-8)
streetNameStreet name.String
distanceLength of segment (in meters or feet according to userPreference).Float
shapeGeometrical shape of segment.List of pairs: longitude & latitude
segmentProbeCountsSee the segmentProbeCounts section.List

Structure of segmentProbeCounts

Field(s)DescriptionType / Values
timeSetReference to TimeSet in which calculations were made.Integer
dateRangeReference to DateRange in which calculations were made.Integer
probeCountThe 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.Integer