Sorry, you need to enable JavaScript to visit this website.

Traffic Density

The Traffic Density API gives insight in amount of data available for an area. This API 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 GET request to the check job's status. When job is successfully finished user in response will receive links to download results.

There are some important notes about using this API:

  • 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 number of time sets is 24.
  • The bounding box cannot be grater 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 progress per each developer key. In progress job means one in NEW, MAPMATCHING, MAPMATCHED, READING_GEOBASE, CALCULATIONS status. When you reach this limit, API response is going to present you a validation message with list of all jobs that you currently have in progress. You may create next job when one of currently running jobs is done. 

Request

Format

https://<baseURL>/traffic/trafficstats/trafficdensity/<versionNumber>?key=<apiKey>

Required POST Headers

Content-Type: application/json

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

Below JSON parameters refer to POST request.

Parameter Parameter Req'd? Type / Values Default Value
jobName Job name. Given for user's convenience. Yes String
distanceUnit Base unit used for distance and speed. Yes
  • KILOMETERS
  • MILES
averageSampleSizeThreshold If average sample size for any combination of network, date range and time set will be lower than given value then output will not be generated, job will be moved into REJECTED state and user will not be charged for such report. If not specified output will be always generated no matter how many samples were available. No Integer
network Network for calculations. See structure here. Yes Object
dateRange Ranges of dates for calculations. Limit the date range to maximum one year in order to restrict the processing time. See structure here. Yes Object
timeSets Time sets for calculations. See structure here. Yes List

Structure of network

Parameter Parameter Req'd? Type / Values Default Value
name Name of the network. Yes String
boundingBox Bounding box of the network. See structure here. Yes Object
zoneId In which time zone all times are given. Yes Time zone like: "Europe/Amsterdam" or "UTC"
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

Structure of boundingBox

Parameter Parameter Req'd? Type / Values Default Value
leftDownCorner Point in left down corner of bounding box

  • latitude - Latitude of start point
  • longitude - Longitude of start point
Yes Longitude & latitude
rightTopCorner Point in right top corner of bounding box

  • latitude - Latitude of end point
  • longitude - Longitude of end point
Yes Longitude & latitude

Structure of dateRange

Parameter Parameter Req'd? Type / Values Default Value
name Date range name. Given for user's convenience. Yes String
from Date from. Yes Date in format: YYYY-MM-DD
to Date to. Yes Date in format: YYYY-MM-DD
exclusions List of days excluded from date range. No List of dates in format: YYYY-MM-DD

Structure of timeSets

Parameter Parameter Req'd? Type / Values Default Value
name Time set name. Given for user's convenience. Yes String
timeGroups Time groups in time set

  • days - Days of week for time group (required)

    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

{
  "jobName":"Test job",
  "distanceUnit":"KILOMETERS",
  "network": {
    "name": "test",
    "boundingBox" : {
      "leftDownCorner": {
        "longitude":17.47197,
        "latitude":52.3159
      },
      "rightTopCorner": {
        "longitude":17.53042,
        "latitude":52.31868
      }
    },
    "timeZoneId": "Europe/Warsaw",
    "frcs": [
      "0",
      "1",
      "2",
      "3",
      "4",
      "5",
      "6",
      "7",
      "8"
    ],
    "probeSource":"ALL"
 },
  "dateRange": {
    "name":"Last working week of April",
    "from":"2015-04-24",
    "to":"2015-04-30",
    "exclusions":[
      "2015-04-25",
      "2015-04-26"
    ]
  },
  "timeSets":[
    {
      "name":"Monday morning hour",
      "timeGroups":[
        {
          "days":[
            "MON"
          ],
          "times":[
            "7:00-8:00"
          ]
        }
      ]
    }
  ]
}

Response

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>

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. Below you find the different stages of the process.

Status Description
NEW The job is waiting for mapmatching to start.
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.
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 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 is less samples then required (see averageSampleSizeThreshold). This can occur at any place in the flow.
EXPIRED The job is older than 90 days and all data has been removed.

Response and Results

Final DONE response

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

Results

Output of Traffic Density is available in JSON and SHAPE format. JSON results are provided in a gzip compressed format. 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 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)
List
timeSets (from request) See structure here. List
network Data for requested network. See structure here. 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 structure here. List

Structure of segmentResults

Field(s) Description Type / Values
segmentId Segment id. Integer
newSegmentId New segment id. 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 Amount of probes available for given segment. See structure here. 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 Number of probes with data available for given segment. Integer