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
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 |
| — |
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 |
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:
| 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:
|
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
| Yes | List | — |
JSON example request
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:
{"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
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
{"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.
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:
https://{baseURL}/traffic/trafficstats/status/{versionNumber}/{job_id}/accept?key={apiKey}
Otherwise reject the job with the following request:
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
| Object |
dateRanges | (from request)
| 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:
| 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 |