Incident Details

Service version: 5
Last edit: 2021.07.30

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.

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

▲ 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.

▲ 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.

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

Error response example

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

HTTP response codes

▲ 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.

▲ Return to top