TomTom LogoDocs
Products
Resources
Pricing
Sign in
Traffic API
Documentation
API Explorer

Incident Details

Service version: 2Last edit: 2026.03.12TomTom Orbis Maps

Purpose

The TomTom Orbis Maps Traffic API Incident Details endpoint provides information on traffic incidents which are inside a given bounding box or whose geometry intersects with it.

  • The data obtained from this service can be used as standalone or as an extension to other Traffic Incident services.
  • Apart from present incident data, it is possible to get information about planned future incidents.

Request data

HTTPS method: GET

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.
get
Request curl command example with bounding box
curl 'https://api.tomtom.com/maps/orbis/traffic/incidents/details?apiVersion=2&bbox=4.8854592519716675,52.36934334773164,4.897883244144765,52.37496348620152&timeValidity=present' -H "TomTom-Api-Key: {Your_API_Key}" -H "Attributes: incidents(type,geometry(type,coordinates),properties(iconCategory))"
get
Request curl command example with IDs
curl 'https://api.tomtom.com/maps/orbis/traffic/incidents/details?apiVersion=2&ids=4819f7d0a15db3d9b0c3cd9203be7ba5&timeValidity=present' -H "TomTom-Api-Key: {Your_API_Key}" -H "Attributes: incidents(type,geometry(type,coordinates),properties(iconCategory))"
get
Request curl command with category filter
curl 'https://api.tomtom.com/maps/orbis/traffic/incidents/details?apiVersion=2&bbox=4.8854592519716675,52.36934334773164,4.897883244144765,52.37496348620152&timeValidity=present&iconCategories=roadWorks' -H "TomTom-Api-Key: {Your_API_Key}" -H "Attributes: incidents(type,geometry(type,coordinates),properties(iconCategory))"

HTTPS method POST

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the tables of required and optional parameters and their values. The generic request format is as follows.
  • The maximum number of incidents IDs in a single POST request is 100.
post
Request curl command example with attributes
curl -X POST 'https://api.tomtom.com/maps/orbis/traffic/incidents/details?apiVersion=2' -H "TomTom-Api-Key: {Your_API_Key}" -H "Attributes: incidents(geometry(type,coordinates),properties(iconCategory))" -d '{
    "ids": [
        "4819f7d0a15db3d9b0c3cd9203be7ba5"
    ]
}'

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 parametersDescription

baseURL
string

The base URL for calling the API.
Value: api.tomtom.com

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.

  • This parameter is mutually exclusive with the ids parameter.

  • This parameter is available only for GET requests.

Values: minLon,minLat,maxLon,maxLat

ids
string

Comma separated list of incidents IDs.

  • The maximum number of incidents IDs is 5 for GET requests.

  • This parameter is mutually exclusive with the bbox parameter.

  • This parameter is available only for GET requests.

Value: A comma separated string

key
string

The authorization key for access to the API.
Please note that using the TomTom-Api-Key header is recommended over the key query parameter for improved security.
Value: Your valid API Key.
Optional parametersDescription

apiVersion
integer

Contains a version of the API to call.
Value: The current version is 2.

iconCategories
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 values: all icon categories
Allowed values:

  • unknown

  • accident

  • fog

  • dangerousConditions

  • rain

  • ice

  • jam

  • laneClosed

  • roadClosed

  • roadWorks

  • wind

  • flooding

  • brokenDownVehicle

timeValidity
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

POST request body

Follow the request body schema in order to prepare a valid POST request.

Request schema

An exclamation mark ! means that the field is not nullable. For example:

  • String! - is non-nullable
  • [String!] - list of non-null objects
  • [String]! - list cannot be null, but it can contain null values
Request body
{
    ids: [String!]!
}

Request headers

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

Required headersDescription
TomTom-Api-Key

The authorization key for access to the API.
Preferred method for authentication. Using the header is recommended over the key query parameter for improved security.
Value: Your valid API Key.

TomTom-Api-Version

Contains a version of the API to call.
Value: The current version is 2.

Attributes

A list of fields to return, specified in dot-notation.
See the Attributes header section for details and examples.
Value: list of the selected fields.
Optional headersDescription
Accept

Advertises which content types, expressed as MIME types, the client is able to understand. In this service, the header is used to specify a preferred response format. If the preferred format is not supported, the server will fall back to the default one.
Value: Accept: application/json

Accept-Encoding

Contains the content encoding (usually a compression algorithm), that the client is able to understand. It is strongly recommended using this header in order to limit bandwidth usage.
Value: gzip

Accept-Language

Contains 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: List of supported languages .

Attributes-Exclude

A list of response fields to omit, specified in dot-notation.
See the Attributes-Exclude header section for details and examples.
Value: list of the selected fields.

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>

Attributes

Attributes header

A list of response fields to return, specified in dot-notation. Nested fields are expressed using . separators and optional grouped subfields using parentheses.
Attributes header must contain at least one valid top-level field. Using only a top-level * wildcard is not allowed.
When a field name refers to a non-primitive object, all its non-EXPLICIT subfields are returned by default unless further restricted in the header. EXPLICIT fields (as documented per API) are only returned when they are explicitly listed in Attributes (they are never included solely by selecting their parent or by using *).
The * wildcard may be used only at non–top-level positions to include all non-EXPLICIT subfields of the selected object.

Syntax:

  • <field-list> ::= <field> (',' <field>)*
  • <field> ::= <name> ('.' <field> | <field-set>)?
  • <field-set> ::= '(' <field-set-list> ')'
  • <field-set-list> ::= '*' (',' <field>)* | <field> (',' <field>)*
  • <name> ::= one or more alphabetic characters

Note:

  • All listed field names must exist in the response schema; unknown fields result in an error.
  • Response schema can be found in Successful response section.
  • APIs may restrict which fields are allowed in Attributes. Disallowed-but-existing fields result in an error.
  • New fields may be added over time. When they are marked EXPLICIT, they are not returned unless explicitly requested via Attributes, preserving backward compatibility and performance.

Examples:

  • incidents.type, incidents.properties.iconCategory
  • incidents(type, geometry(type, coordinates))
  • incidents.properties.*

Attributes-Exclude header

A list of response fields to omit, specified in dot-notation. Nested fields are expressed using . separators and optional grouped subfields using parentheses.
Any field listed in Attributes-Exclude, including its entire sub-tree, is omitted from the response, regardless of whether it was included implicitly or explicitly via the Attributes header. Exclusion always overrules inclusion.
The format of the field list is the same “listed dot-notation” used for the Attributes header:

Syntax:

  • <field-list> ::= <field> (',' <field>)*
  • <field> ::= <name> ('.' <field> | <field-set>)?
  • <field-set> ::= '(' <field-set-list> ')'
  • <field-set-list> ::= '*' (',' <field>)* | <field> (',' <field>)*
  • <name> ::= one or more alphabetic characters

Notes:

  • The exclusion list is applied to the result of the inclusion list. If a parent field is excluded, all of its children are excluded, even if some of those children were explicitly listed in Attributes.
  • When Attributes header inclusion list is not present in the request, then Attributes-Exclude header value is ignored.
  • Listed field names in Attributes-Exclude must exist in the response schema; unknown fields result in an error.
  • Response schema can be found in Successful response section.
  • APIs may restrict which fields are allowed in Attributes-Exclude. Disallowed-but-existing fields result in an error.
  • Fields may occur multiple times in Attributes-Exclude (not recommended, but not an error).
  • Some overlap between Attributes and Attributes-Exclude is allowed. In case of overlap, the exclusion takes precedence.
  • Whether a field is EXPLICIT or not does not change the semantics of exclusion: if it is present in Attributes-Exclude, it is omitted whenever it would otherwise have been returned.
  • If all fields are excluded, then HTTP 204 No Content response is returned.

Example:
Attributes: incidents.properties.*
Attributes-Exclude: incidents.properties.iconCategory
Results in returning properties for all incidents present in the response except iconCategory property.

Response data

Successful response

For a single request, the Traffic API Incident Details endpoint returns its response body in JSON format.

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

Notice:

  • The definition of type Query varies from the request method (and from the query parameter used in the GET request).
  • For the GET method with the bbox query parameter, the mentioned type is defined as follows.
type Query
type Query {
  incidents : [Incident!]!
}
  • In the response for the GET method with the ids query parameter or POST, the non-existing incidents for specific incident IDs will be present as null.
  • In that case, Query type is defined as follows.
type Query
type Query {
  incidents : [Incident]!
}

The rest of the scheme is the same for each variant.

Common part of response scheme
type Incident
type Incident {
    type: GeojsonFeatureType!
    geometry : GeojsonGeometry!
    properties: IncidentProperties!
}
type IncidentProperties, Event, GeojsonGeometry, GeojsonLinestring, Aci
type IncidentProperties {
    id : String!
    iconCategory  : String!
    magnitudeOfDelay : String!
    events : [Event!]!
    startTime : String
    endTime : String
    from : String
    to : String
    lengthInMeters : Float!
    delayInSeconds : Int
    roadNumbers : [String!]!
    timeValidity : TimeValidity!
    probabilityOfOccurrence : ProbabilityOfOccurrence!
    numberOfReports : Int
    lastReportTime : String
}


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


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
}


enum ProbabilityOfOccurrence {
    certain
    probable
    risk_of
    improbable
}


enum Direction {
    positive
    negative
}


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

FieldDescription

incidents
object

Incidents which belong to or intersect with the given bounding box.

Structure of the Incident object

FieldDescription

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

FieldDescription

id
string

The ID of the traffic incident, common among Traffic Incident API services where it is available.

iconCategory
string

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:

  • unknown

  • accident

  • fog

  • dangerousConditions

  • rain

  • ice

  • jam

  • laneClosed

  • roadClosed

  • roadWorks

  • wind

  • flooding

  • brokenDownVehicle

magnitudeOfDelay
string

The magnitude of delay associated with an incident. The values meaning:

  • unknown

  • minor

  • moderate

  • major

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

lengthInMeters float

The length of the incident in meters.

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

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.

Structure of the Event object

FieldDescription

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
string

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.
Response example - JSON
{
  "incidents": [
    {
      "type": "Feature",
      "properties": {
        "iconCategory": "roadClosed"
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [4.8905266414, 52.3725919469],
          [4.8905306647, 52.372535656],
          [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.371663905],
          [4.8905936966, 52.371524454],
          [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.370765372],
          [4.8900062928, 52.370581651],
          [4.8899472842, 52.3705320104]
        ]
      }
    }
  ]
}
Response example with available fields - JSON
{
  "incidents" : [
    {
      "type" : "Feature",
      "properties" : {
        "id":"4819f7d0a15db3d9b0c3cd9203be7ba5",
        "iconCategory" : "roadClosed",
        "magnitudeOfDelay" : "undefined",
        "startTime" : "2021-02-02T15:37:00Z",
        "endTime" : "2021-04-30T22:00:00Z",
        "from" : "Paleisstraat",
        "to" : "Rosmarijnsteeg",
        "lengthInMeters" : 238.553,
        "delayInSeconds" : 0,
        "roadNumbers" : [],
        "timeValidity" : "present",
        "events" : [
          {
            "code" : 401,
            "description" : "Closed",
            "iconCategory" : "roadClosed"
          }
        ],
      "probabilityOfOccurrence" : "certain",
      "numberOfReports" : null,
      "lastReportTime" : 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]]
      }
    }
  ]
}

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.

Error response field structure

FieldDescription

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 - JSON
{
  "detailedError ": {
    "code": "INVALID_REQUEST",
    "message": "Unknown field in fields=incidents.properties.last"
  }
}

HTTP response codes

CodeMeaning & possible causes
200

OK

204

No content: When all response fields are excluded by Attributes-Exclude header.

400

Bad request: Usually due to a malformed syntax.

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

HTTP response headers

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

HeaderDescription
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.
Values: GET, POST, HEAD

Cache-Control

Contains directives for a caching mechanism.

Value: max-age=<number>

Content-Encoding

Indicates which encodings were applied to the response body.
Value: gzip

Content-Language

Contains information about the content language inside the response body. Value: <language tag>

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>

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>