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

Incident Details

 

Service version: 5
Last edit: 2021.07.20

On this page

Important note

This is the new and improved version (5) of the Incident Details endpoint. We highly recommend that you use this new version 5 rather than the old version 4, which we marked as deprecated.

Purpose

The Incident Details service provides information on traffic incidents which are inside a given bounding box or whose geometry intersects with it.

  • The freshness of data is based on the provided Traffic Model ID.
  • The data obtained from this service can be used as standalone or as an extension to other Traffic Incident services.
    • In the second case, the same Traffic Model ID should be used when calling all services, in order to grant synchronization of data between APIs.
  • Apart from present incident data, it is possible to get information about planned future incidents.

Run this endpoint

You can easily run this and other endpoints.

  1. Go to the TomTom API Explorer page.
  2. Click an endpoint.
    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  3. Review the response.

Request data

HTTPS method: GET

URL format

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.
https://baseURL/traffic/services/versionNumber/incidentDetails?key=Your_Api_Key&bbox=minLon,minLat,maxLon,maxLat&fields=string&language=string&t=Traffic_Model_Id&categoryFilter=string&timeValidityFilter=string

Example

https://api.tomtom.com/traffic/services/5/incidentDetails?key=Your_Api_Key&bbox=4.8854592519716675,52.36934334773164,4.897883244144765,52.37496348620152&fields={incidents{type,geometry{type,coordinates},properties{iconCategory}}}&language=en-GB&t=1111&timeValidityFilter=present

curl command

curl 'https://api.tomtom.com/traffic/services/5/incidentDetails?key=Your_Api_Key&bbox=4.8854592519716675,52.36934334773164,4.897883244144765,52.37496348620152&fields={incidents{type,geometry{type,coordinates},properties{iconCategory}}}&language=en-GB&t=1111&timeValidityFilter=present'

Example with category filter

https://api.tomtom.com/traffic/services/5/incidentDetails?key=Your_Api_Key&bbox=4.8854592519716675,52.36934334773164,4.897883244144765,52.37496348620152&fields={incidents{type,geometry{type,coordinates},properties{iconCategory}}}&language=en-GB&t=1111&categoryFilter=Accident&timeValidityFilter=present

curl command

curl 'https://api.tomtom.com/traffic/services/5/incidentDetails?key=Your_Api_Key&bbox=4.8854592519716675,52.36934334773164,4.897883244144765,52.37496348620152&fields={incidents{type,geometry{type,coordinates},properties{iconCategory}}}&language=en-GB&t=1111&categoryFilter=Accident&timeValidityFilter=present'

Example with all available fields

https://api.tomtom.com/traffic/services/5/incidentDetails?key=Your_Api_Key&bbox=4.8854592519716675,52.36934334773164,4.897883244144765,52.37496348620152&fields={incidents{type,geometry{type,coordinates},properties{id,iconCategory,magnitudeOfDelay,events{description,code,iconCategory},startTime,endTime,from,to,length,delay,roadNumbers,timeValidity,aci{probabilityOfOccurrence,numberOfReports,lastReportTime},tmc{countryCode,tableNumber,tableVersion,direction,points{location,offset}}}}}&language=en-GB&t=1111&categoryFilter=0,1,2,3,4,5,6,7,8,9,10,11,14&timeValidityFilter=present,future

curl command

curl 'https://api.tomtom.com/traffic/services/5/incidentDetails?key=Your_Api_Key&bbox=4.8854592519716675,52.36934334773164,4.897883244144765,52.37496348620152&fields={incidents{type,geometry{type,coordinates},properties{id,iconCategory,magnitudeOfDelay,events{description,code,iconCategory},startTime,endTime,from,to,length,delay,roadNumbers,timeValidity,aci{probabilityOfOccurrence,numberOfReports,lastReportTime},tmc{countryCode,tableNumber,tableVersion,direction,points{location,offset}}}}}&language=en-GB&t=1111&categoryFilter=0,1,2,3,4,5,6,7,8,9,10,11,14&timeValidityFilter=present,future'

Request parameters

The following table describes all of the parameters that can be used in a request.

  • Parameters and values are case-sensitive.
  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
Required parameters
Parameter Description
baseURL
string
The base URL for calling the API.
Value: api.tomtom.com
versionNumber
string
The service version number.
Value: The current value is 5.
bbox
float,float,float,float
The corners of the area to report on, expressed in the EPSG:4326 projection.
  • These are two longitude-latitude pairs describing the corners of the bounding box.
  • The first pair is for the lower-left corner and the second pair for the upper-right corner.
  • All values should be separated by a comma.
  • The maximum area of a bounding box is 10'000 km2.
Values: minLon,minLat,maxLon,maxLat
key
string
The authorization key for access to the API.
Value: Your valid API Key.
Optional parameters
Parameter Description
fields
string
The fields to be included in the response, nested as in the response schema. In order to obtain all data, it is necessary to place the whole object in the query.
Default value: {incidents{type,geometry{type,coordinates},properties{iconCategory}}}
Value with all available fields:
{
  incidents{
    type,
    geometry{
      type,
      coordinates
    },
    properties{
      id,
      iconCategory,
      magnitudeOfDelay,
      events{
        description,
        code,
        iconCategory
      },
      startTime,
      endTime,
      from,
      to,
      length,
      delay,
      roadNumbers,
      timeValidity,
      aci{
        probabilityOfOccurrence,
        numberOfReports,
        lastReportTime
      },
      tmc{
        countryCode,
        tableNumber,
        tableVersion,
        direction,
        points{
          location,
          offset
        }
      }
    }
  }
}
language
string
The language code for the output language. Affects the description fields in the response.
When an incident description does not have a translation, an English description is returned.
Default value: en-GB
Allowed values:
  • ar
  • ca-ES
  • cs-CZ
  • da-DK
  • de-DE
  • el-GR
  • en-GB
  • en-US
  • es-ES
  • et-EE
  • fi-FI
  • fr-FR
  • he-IL
  • hu-HU
  • id-ID
  • it-IT
  • lt-LT
  • lv-LV
  • nb-NO
  • nl-NL
  • pl-PL
  • pt-PT
  • ro-RO
  • ru-RU
  • sk-SK
  • sv-SE
  • th-TH
  • tr-TR
  • zh-TW
t
string
The Traffic Model ID is the reference value for the state of traffic at a particular time. It is updated every minute, and is valid for two minutes before it times out.
See the Response Headers section for more information.
Default value: current Traffic Model ID
Allowed value: Traffic_Model_ID
categoryFilter
string
This filter allows the choice of types of incidents and future incidents to be included in the response.
Filtering takes into account the main icon category of the incident. Both value types can be used: numeric and descriptive strings. Multiple values are supported and should be separated by a comma.
Default value: 0,1,2,3,4,5,6,7,8,9,10,11,14
Allowed values:
  • 0: Unknown
  • 1: Accident
  • 2: Fog
  • 3: DangerousConditions
  • 4: Rain
  • 5: Ice
  • 6: Jam
  • 7: LaneClosed
  • 8: RoadClosed
  • 9: RoadWorks
  • 10: Wind
  • 11: Flooding
  • 14: BrokenDownVehicle
timeValidityFilter
string
This filter allows the choice of incidents based on their occurrence in time. Multiple values are supported and they should be separated by a comma.
Default value: present
Allowed values:
  • present
  • future

▲ Return to top

HTTP request headers

The following table lists HTTP request headers of particular interest to clients of the Traffic API Incident Details endpoint.

Required headers
There are no required headers in this endpoint.
Optional headers
Parameter Description
Accept-Encoding Contains the content encoding (usually a compression algorithm), that the client is able to understand.
Value: gzip
Tracking-ID Specifies an identifier for the request.
  • It can be used to trace a call.
  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.
  • An example of the format that matches this regular expression is a UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1). For details check RFC 4122.
  • If specified, it is replicated in the Tracking-ID response header.
  • It is only meant to be used for support and does not involve tracking of you or your users in any form.
Value: <string>

▲ Return to top

Response data

Successful response

For a single request, the Traffic API Incident Details endpoint returns its response body in JSON format. The fields that appear in the JSON response depend on the value of the fields request parameter.

Response schema

The exclamation mark ! means that a particular field cannot be equal to null, for example:

  • Point! - value cannot be equal to null
  • [Point!] - array of non-null objects
  • [Point]! - array cannot be null, but it can contain null values
type Query {
  incidents : [Incident!]!
}

type Incident {
    type: GeojsonFeatureType!
    geometry : GeojsonGeometry!
    properties: IncidentProperties!
}

type IncidentProperties {
    id : String!
    iconCategory  : Int!
    magnitudeOfDelay : Int!
    events : [Event!]!
    startTime : String
    endTime : String
    from : String
    to : String
    length : Float!
    delay : Int
    roadNumbers : [String!]!
    timeValidity : TimeValidity!
    aci : Aci
    tmc : Tmc
}

type Event {
    description : String!
    code : Int!
    iconCategory : Int!
}

union GeojsonGeometry = GeojsonPoint | GeojsonLinestring

type GeojsonPoint {
    type : GeojsonPointType!
    coordinates : [Float!]!
}

type GeojsonLinestring {
    type : GeojsonLinestringType!
    coordinates : [[Float!]!]!
}

enum GeojsonLinestringType {
    LineString
}

enum GeojsonPointType {
    Point
}

enum GeojsonFeatureType {
    Feature
}

type Aci {
    probabilityOfOccurrence : ProbabilityOfOccurrence!
    numberOfReports : Int!
    lastReportTime : String!
}

enum ProbabilityOfOccurrence {
    certain
    probable
    risk_of
    improbable
}

type Tmc {
    countryCode: String!
    tableNumber: String!
    tableVersion: String!
    direction: Direction!
    points [TmcPoint!]!
}

enum Direction {
    positive
    negative
}

type TmcPoint {
    location : Int!
    offset: Int
}

enum TimeValidity {
    present
    future
}

Response field structure

The following table describes JSON element fields that can appear in a response.

Structure of the root object
Field Description
incidents
object
Incidents which belong or intersect with the given bounding box.
Structure of the Incident object
Field Description
type
string
The value is set as Feature (GeoJSON feature object).
geometry
object
A GeoJSON feature of type Point or Linestring (depending on the incident).
It always contains the type and coordinates fields.
properties
object
The properties of a particular incident.
Structure of the IncidentProperties object
Field Description
id
string
The ID of the traffic incident, common among Traffic Incident API services where it is available.
iconCategory
integer
The main icon category associated with this incident. This is an icon category associated with the first event in the events list describing the incident. The values meaning:
  • 0: Unknown
  • 1: Accident
  • 2: Fog
  • 3: Dangerous Conditions
  • 4: Rain
  • 5: Ice
  • 6: Jam
  • 7: Lane Closed
  • 8: Road Closed
  • 9: Road Works
  • 10: Wind
  • 11: Flooding
  • 14: Broken Down Vehicle
magnitudeOfDelay
integer
The magnitude of delay associated with an incident. The values meaning:
  • 0: Unknown
  • 1: Minor
  • 2: Moderate
  • 3: Major
  • 4: Undefined (used for road closures and other indefinite delays)
events
object
The list of events describing the details of the incident in the language requested. Traffic incident can be described with more than one Event object.
startTime
string
Start time of the incident, if available. The date is described in the ISO8601 format.
endTime
string
End time of the incident, if available. The date is described in the ISO8601 format.
from
string
The name of the location where the traffic due to the incident starts.
to
string
The name of the location where the traffic due to the incident ends.
length
float
The length of the incident in meters.
delay
integer
The delay in seconds caused by the incident (except road closures).
It is calculated against free-flow travel time (the travel time when the traffic is minimal, e.g., night traffic).
roadNumbers
array of strings
The road number(s) affected by the incident.
timeValidity
string
Enumeration string describing if the incident occurrence is now or in the future.
aci
object
The Community Attributes (ACI).
tmc
object
TMC (Traffic Message Channel) data of the traffic incident, needed to determine its location.
Structure of the Event object
Field Description
description
string
The description of the event (being part of incident) in the requested language.
code
integer
The predefined alert code, describing the event (part of incident).
iconCategory
integer
The icon category associated with the event. The icon category from the first event in the list is replicated in the iconCategory field in the IncidentProperties object.
Structure of the ACI object
Field Description
probabilityOfOccurrence
string
Enumeration string specifying the likelihood of the occurring incident.
Allowed values:
  • certain
  • probable
  • risk_of
  • improbable
numberOfReports
integer
The number of reports given by actual end-users.
lastReportTime
string
The date in ISO8601 format, when the last time the incident was reported. Gives the user confidence that the incident is fresh.

Response example

{
  "incidents" : [
    {
      "type" : "Feature",
      "properties" : {
        "iconCategory" : 8
      },
      "geometry" : {
        "type" : "LineString",
        "coordinates" : [[4.8905266414,52.3725919469],[4.8905306647,52.3725356560],[4.8905360291,52.3724806443],[4.8905387113,52.3724028603],[4.8905440757,52.3723505607],[4.8905467579,52.3722754886],[4.8905574868,52.3721722195],[4.8905762622,52.3719066767],[4.8905963788,52.3716639050],[4.8905936966,52.3715244540],[4.8905749211,52.3714278871],[4.8905440757,52.3713393544],[4.8905065248,52.3712669418],[4.8904555628,52.3711703743],[4.8904166708,52.3711100387],[4.8903268168,52.3709759593],[4.8901725898,52.3707653720],[4.8900062928,52.3705816510],[4.8899472842,52.3705320104]]
        }
      }
  ]
}

Response example with available fields

{
  "incidents" : [
    {
      "type" : "Feature",
      "properties" : {
        "id":"4819f7d0a15db3d9b0c3cd9203be7ba5",
        "iconCategory" : 8,
        "magnitudeOfDelay" : 4,
        "startTime" : "2021-02-02T15:37:00Z",
        "endTime" : "2021-04-30T22:00:00Z",
        "from" : "Paleisstraat",
        "to" : "Rosmarijnsteeg",
        "length" : 238.553,
        "delay" : 0,
        "roadNumbers" : [],
        "timeValidity" : "present",
        "events" : [
          {
            "code" : 401,
            "description" : "Closed",
            "iconCategory" : 8
          }
        ],
        "aci" : null,
        "tmc" : null
      },
      "geometry" : {
        "type" : "LineString",
        "coordinates" : [[4.8905266414,52.3725919469],[4.8905306647,52.3725356560],[4.8905360291,52.3724806443],[4.8905387113,52.3724028603],[4.8905440757,52.3723505607],[4.8905467579,52.3722754886],[4.8905574868,52.3721722195],[4.8905762622,52.3719066767],[4.8905963788,52.3716639050],[4.8905936966,52.3715244540],[4.8905749211,52.3714278871],[4.8905440757,52.3713393544],[4.8905065248,52.3712669418],[4.8904555628,52.3711703743],[4.8904166708,52.3711100387],[4.8903268168,52.3709759593],[4.8901725898,52.3707653720],[4.8900062928,52.3705816510],[4.8899472842,52.3705320104]]
      }
    }
  ]
}

▲ Return to top

Error response

If there is an error in the supplied parameters or any other internal problem, an error response is generated in the requested format. If the contentType parameter could not be parsed, XML will be returned.

Error response field structure

Field Description
detailedError{}
object
Main object of the error response.
code
string
One of a server-defined set of error codes.
message
string
A human-readable description of the error code.

Error response example

{
  "detailedError ": {
    "code" : "INVALID_REQUEST",
    "message" : "Unknown field in fields=incidents.properties.aci.last"
  }
}

HTTP response codes

Code Meaning & possible causes
200 OK
400 Bad request, usually due to a malformed syntax or old Traffic Model ID.
403 Forbidden: The supplied API Key is not valid for this request.
405 Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource.
429 Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.
500 Internal Server Error

▲ Return to top

HTTP response headers

The following table lists HTTP response headers of particular interest to clients of the Traffic API Incident Details endpoint.

Header Description
Access-Control-Allow-Origin Indicates that cross-origin resource sharing (CORS) is allowed.
Value: *
Allow Lists the set of supported HTTP methods. The header is sent in case a 405 HTTP response code is returned.
Value: GET, HEAD
Content-Encoding Indicates which encodings were applied to the response body.
Value: gzip
Content-Length Contains information about the size of the response body.
Value: <decimal number>
Content-Type Indicates the media type of the resource returned.
Value: <application/json; charset=utf-8>
Date Contains the date and time when the message was originated.
Value: <http-date>
TrafficModelID Contains the reference value for the state of traffic at a particular time.
  • If the request contains a valid Traffic Model ID, its value is replicated here.
  • If the request does not contain a Traffic Model ID, the most recent one is returned.
Value: <numeric>
Tracking-ID An identifier for the request.
  • If the Tracking-ID header was specified in the request, it is replicated in the response.
  • Otherwise, it is generated automatically by the service. For details check RFC 4122.
  • It is only meant to be used for support and does not involve tracking of you or your users in any form.
Value: <string>

▲ Return to top