Traffic Density

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

Header	Value
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.

Parameter	Description	Req'd?	Type / Values	Default Value
baseURL	Base URL for calling the API.	Yes	api.tomtom.com	—
versionNumber	Service version number. The current value is 1.	Yes	1	—
apiKey	Authorization key for access to the API.	Yes	API Key	—

JSON request parameters

The following JSON parameters refer to the POST request.

Parameter	Description	Req'd?	Type / Values	Default Value
jobName	Job name. Given for the user's convenience.	Yes	String	—
distanceUnit	Base unit used for distance and speed.	Yes	KILOMETERS MILES	—
mapVersion	What map should be used. List of currently available maps in all Traffic Stats API services can be checked at Available Maps.	No	String	2016.12
acceptMode	Defines whether the job should be accepted manually or automatically.	No	AUTO MANUAL	AUTO
averageSampleSizeThreshold	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 user will not be charged for such report. If not specified the output will be always generated no matter how many samples were available.	No	Integer	—
network	Network for calculations. See the Structure of network section.	Yes	Object	—
dateRange	Range of dates for calculations. See the Structure of dateRange section.	Yes	Object	—
timeSets	Time sets for calculations. See the Structure of timeSets section.	Yes	List	—

Structure of network

Parameter	Description	Req'd?	Type / Values	Default Value
name	Name of the network.	Yes	String	—
timeZoneId	In which time zone all times are given.	Yes	String Time zone like: "Europe/Amsterdam" or "UTC". See time zone names from tz database for more.	—
frcs	Functional road classes.	Yes	List of Integers from range 0-8	—
probeSource	Determines from what devices data will be used. Possible values: PASSENGER - Passenger Vehicles TELEMATICS - Fleet Management Vehicles ALL - All Vehicles (Passenger and Fleet combined)	No	String ALL, PASSENGER, TELEMATICS	PASSENGER
geometry	Geometry of the network in GeoJSON format. Supported geometry types are Polygon and MultiPolygon. See RFC 7946.	Yes	Object	—
boundingBox	Bounding box of the network. Mutually exclusive with geometry. Deprecated, please use geometry.	No	Object	—

Structure of dateRange

Parameter	Description	Req'd?	Type / Values	Default Value
name	Date range name. Given for the user's convenience.	Yes	String	—
from	Date from (inclusive).	Yes	Date in format: YYYY-MM-DD	—
to	Date to (inclusive).	Yes	Date in format: YYYY-MM-DD.	—
exclusions	List of days excluded from date range.	No	List of dates in format: YYYY-MM-DD.	—
excludedDaysOfWeek	List of days of week to be excluded.	No	List of values: MON TUE WED THU FRI SAT SUN

Structure of timeSets

Parameter	Description	Req'd?	Type / Values	Default Value
name	Time set name. Given for the user's convenience.	Yes	String	—
timeGroups	Time 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).	Yes	List	—

JSON example request

POST
Request body - JSON
1{
"jobName":"Test job",
"distanceUnit":"KILOMETERS",
"mapVersion" : "2020.09",
"acceptMode" : "AUTO",
"network": {
  "name": "test",
    "geometry" : {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [
          [19.44305, 51.75612],
          [19.44992, 51.75612],
          [19.44992, 51.75947],
          [19.44305, 51.75947],
          [19.44305, 51.75612]
        ]
      ],
      [
        [
          [19.45011, 51.75789],
          [19.45687, 51.75789],
          [19.45687, 51.75946],
          [19.45011, 51.75946],
          [19.45011, 51.75789]
        ]
      ]
    ]
  },
  "timeZoneId": "Europe/Warsaw",
  "frcs": [
    "0",
    "1",
    "2",
    "3",
    "4",
    "5",
    "6",
    "7",
    "8"
  ],
  "probeSource":"ALL"
44},
"dateRange":
  {
    "name":"Last working week of January",
    "from":"2021-01-25",
    "to":"2021-01-29",
    "exclusions":[
      "2021-01-26",
      "2021-01-27"
    ]
  },
"timeSets":[
  {
    "name":"Monday morning hour",
    "timeGroups":[
      {
        "days":[
          "MON"
        ],
        "times":[
          "7:00-8:00"
        ]
      }
    ]
  }
]
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.

Parameter	Description	Req'd?	Type / Values	Default Value
baseURL	Base URL for calling the API.	Yes	api.tomtom.com	—
versionNumber	Service version number. The current value is 1.	Yes	1	—
apiKey	Authorization key for access to the API.	Yes	API 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.

Status	Description
NEW	The job is waiting for mapmatching to start.
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 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, 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.
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.

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{
  "summaries": [
      {
          "locationName": "test",
          "dateRangeName": "Last working week of January",
          "timeSetName": "Monday morning hour",
          "averageSampleSize": 17.06,
          "frcDetails": [
              {
                  "frc": 0,
                  "averageSampleSize": 0.0,
                  "networkLength": 0.0,
                  "distanceUnit": "KILOMETERS"
              },
              {
                  "frc": 1,
                  "averageSampleSize": 0.0,
                  "networkLength": 0.0,
                  "distanceUnit": "KILOMETERS"
              },
              {
                  "frc": 2,
                  "averageSampleSize": 0.0,
                  "networkLength": 0.0,
                  "distanceUnit": "KILOMETERS"
              },
              {
                  "frc": 3,
                  "averageSampleSize": 0.0,
                  "networkLength": 0.0,
                  "distanceUnit": "KILOMETERS"
              },
              {
                  "frc": 4,
                  "averageSampleSize": 30.08,
                  "networkLength": 5.41,
                  "distanceUnit": "KILOMETERS"
              },
              {
                  "frc": 5,
                  "averageSampleSize": 11.96,
                  "networkLength": 0.78,
                  "distanceUnit": "KILOMETERS"
              },
              {
                  "frc": 6,
                  "averageSampleSize": 5.63,
                  "networkLength": 1.22,
                  "distanceUnit": "KILOMETERS"
              },
              {
                  "frc": 7,
                  "averageSampleSize": 0.77,
                  "networkLength": 4.55,
                  "distanceUnit": "KILOMETERS"
              },
              {
                  "frc": 8,
                  "averageSampleSize": 0.0,
                  "networkLength": 0.0,
                  "distanceUnit": "KILOMETERS"
              }
          ]
      }
  ]
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)	Description	Type / Values
jobName	(from request)	(as in request)
creationTime	Job creation time.	Timestamp in the format:yyyy-MM-ddTHH:mm:ss.SSSZ
userPreference	Requested 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
network	Data for requested network. See the Structure of network section.	Object

Structure of timeSets

Field(s)	Description	Type / Values
@id	Helper reference for further use (in network.segmentResults.segmentProbeCounts).	Integer
name	(from request)	(as in request)
dayToTimeRanges	Time 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)	Description	Type / Values
networkName, zoneId, probeSource	(from request)	(as in request)
mapsVersions	Version of maps used for map matching.	String
segmentResults	Data for each segment in given area. See the segmentResults section.

Structure of segmentResults

Field(s)	Description	Type / Values
segmentId	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.	Long
newSegmentId	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 other not) or stringified numeric value.	String
speedLimit	Speed limit (in kmph or mph according to userPreference).	Integer
frc	Functional Road Class.	Integer (0-8)
streetName	Street name.	String
distance	Length of segment (in meters or feet according to userPreference).	Float
shape	Geometrical shape of segment.	List of pairs: longitude & latitude
segmentProbeCounts	See the segmentProbeCounts section.	List

Structure of segmentProbeCounts

Field(s)	Description	Type / Values
timeSet	Reference to TimeSet in which calculations were made.	Integer
dateRange	Reference to DateRange in which calculations were made.	Integer
probeCount	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.	Integer

Purpose

Using this service

Request data

HTTPS method: POST

URL format

Required headers

Request Parameters

JSON request parameters

Structure of network

Structure of dateRange

Structure of timeSets

JSON example request

Response data

Check job status

JSON request

Job status parameters

JSON response

Job status flow

Confirming job results

Response and Results

Final DONE response

Results

JSON result description

Structure of timeSets

Structure of network

Structure of segmentResults

Structure of segmentProbeCounts

HTTPS method: `POST`