Incident Details

VERSION 0.46.1 PUBLIC PREVIEW

The Incident Details service provides real-time and scheduled traffic incident data for a geographic area or a list of known incident IDs. Each incident is a GeoJSON Feature with a Point or LineString geometry, making results easy to display on a map or process server-side.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { geocodeOne, trafficIncidentDetails } from '@tomtom-org/maps-sdk/services';
import { API_KEY } from './config';

TomTomConfig.instance.put({ apiKey: API_KEY });

(async () => {
    const place = await geocodeOne('Amsterdam');

    const result = await trafficIncidentDetails({
        bbox: place,
        timeValidityFilter: ['present'],
    });

    console.log(`Found ${result.features.length} incident(s)\n`);

    for (const incident of result.features) {
        console.log(JSON.stringify(incident.properties, null, 4));
    }
})();

Core Concepts

Traffic incidents are described by:

Category (category): the type of incident — accident, roadworks, jam, road-closed, etc.
Delay magnitude: how severe the delay is — minor, moderate, major, or indefinite (road closures).
Geometry: a Point for localised incidents, or a LineString for incidents spanning a road stretch.
Time validity: whether the incident is present (active now) or future (scheduled).
Events: one or more descriptions of what is happening at the incident location.

Basic Usage

Query by Bounding Box

The bbox parameter accepts a raw [minLon, minLat, maxLon, maxLat] tuple, or any GeoJSON object — the bounding box is calculated automatically from the geometry:

1
import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
2
import { geocodeOne, trafficIncidentDetails } from '@tomtom-org/maps-sdk/services';
3

4
TomTomConfig.instance.put({ apiKey: 'your-api-key' });
5

6
// Pass a geocoded place directly — no manual bbox extraction needed
7
const place = await geocodeOne('Amsterdam');
8
const result = await trafficIncidentDetails({ bbox: place });
9

10
result.features.forEach(incident => {
11
    const { category, magnitudeOfDelay, from, to } = incident.properties;
12
    console.log(`${category} — ${magnitudeOfDelay} delay: ${from} → ${to}`);
13
});

You can also pass a raw tuple when you already have the coordinates:

1
const result = await trafficIncidentDetails({
2
    bbox: [4.728, 52.278, 5.08, 52.479]  // [minLon, minLat, maxLon, maxLat]
3
});

Query by Incident IDs

When you already know the IDs of the incidents you are interested in, look them up directly:

1
const result = await trafficIncidentDetails({
2
    ids: ['incident-id-1', 'incident-id-2', 'incident-id-3']
3
});

Filtering Results

By Category

Use categoryFilter to restrict results to specific incident types:

1
const result = await trafficIncidentDetails({
2
    bbox: [4.728, 52.278, 5.08, 52.479],
3
    categoryFilter: ['accident', 'road-closed']
4
});

Available category values:

Value	Description
`'accident'`	Traffic accident or collision
`'animals-on-road'`	Animals present on the road
`'broken-down-vehicle'`	Vehicle breakdown causing obstruction
`'danger'`	Dangerous situation on the road
`'flooding'`	Flooded road section
`'fog'`	Fog reducing visibility
`'frost'`	Frost or ice on the road
`'jam'`	Traffic congestion or slow-moving traffic
`'lane-closed'`	One or more lanes closed
`'narrow-lanes'`	Lane narrowing reducing road capacity
`'other'`	Other types of incidents
`'rain'`	Heavy rain affecting driving conditions
`'road-closed'`	Road is closed or blocked
`'roadworks'`	Construction or maintenance work
`'wind'`	Strong wind conditions affecting traffic

By Time Validity

By default only 'present' (currently active) incidents are returned. Include 'future' incidents to see planned works and scheduled events:

1
const result = await trafficIncidentDetails({
2
    bbox: [4.728, 52.278, 5.08, 52.479],
3
    timeValidityFilter: ['present', 'future']
4
});

Working with Incident Data

Reading Incident Properties

1
const incident = result.features[0];
2

3
// Geometry — Point or LineString
4
console.log(incident.geometry.type);        // 'Point' | 'LineString'
5
console.log(incident.geometry.coordinates); // [lon, lat] or [[lon, lat], ...]
6

7
const {
8
    id,
9
    category,            // 'accident' | 'jam' | 'roadworks' | 'road-closed' | …
10
    magnitudeOfDelay,    // 'minor' | 'moderate' | 'major' | 'indefinite' | 'unknown'
11
    events,
12
    from,
13
    to,
14
    lengthInMeters,
15
    delayInSeconds,
16
    roadNumbers,
17
    timeValidity,        // 'present' | 'future'
18
    probabilityOfOccurrence,  // 'certain' | 'probable' | 'risk_of' | 'improbable'
19
    startTime,           // Date | undefined
20
    endTime,             // Date | undefined
21
    tmc,                 // TMC data | undefined
22
} = incident.properties;

Displaying on a Map

Incident results are standard GeoJSON features and integrate directly with the TomTom Maps SDK:

1
import maplibregl from 'maplibre-gl';
2

3
const result = await trafficIncidentDetails({
4
    bbox: [4.728, 52.278, 5.08, 52.479]
5
});
6

7
// Add incidents as a GeoJSON source
8
map.addSource('incidents', {
9
    type: 'geojson',
10
    data: {
11
        type: 'FeatureCollection',
12
        features: result.features
13
    }
14
});
15

16
// Style Point incidents as circles
17
map.addLayer({
18
    id: 'incident-points',
19
    type: 'circle',
20
    source: 'incidents',
21
    filter: ['==', ['geometry-type'], 'Point'],
22
    paint: {
23
        'circle-radius': 8,
24
        'circle-color': [
25
            'match', ['get', 'category'],
26
            'accident',   '#e74c3c',
27
            'jam',        '#e67e22',
28
            'road-closed','#c0392b',
29
            'roadworks',  '#f39c12',
30
            '#3498db'  // default
31
        ]
32
    }
33
});
34

35
// Style LineString incidents as lines
36
map.addLayer({
37
    id: 'incident-lines',
38
    type: 'line',
39
    source: 'incidents',
40
    filter: ['==', ['geometry-type'], 'LineString'],
41
    paint: {
42
        'line-width': 4,
43
        'line-color': '#e74c3c'
44
    }
45
});

Filtering by Severity

Focus on the most impactful incidents by filtering client-side on magnitudeOfDelay:

1
const severeIncidents = result.features.filter(incident =>
2
    incident.properties.magnitudeOfDelay === 'major' ||
3
    incident.properties.magnitudeOfDelay === 'indefinite'
4
);

Advanced Options

Traffic Model ID

For consistency across multiple traffic API calls made at the same time, pass the same trafficModelId. Obtain it from the Traffic Flow API:

1
const result = await trafficIncidentDetails({
2
    bbox: [4.728, 52.278, 5.08, 52.479],
3
    trafficModelId: '1234567890'
4
});

Custom Service Customization

The trafficIncidentDetails function accepts an optional second argument for advanced request/response customization, following the same pattern as other SDK services:

1
import { trafficIncidentDetails } from '@tomtom-org/maps-sdk/services';
2

3
const result = await trafficIncidentDetails(
4
    { bbox: [4.728, 52.278, 5.08, 52.479] },
5
    {
6
        // Override the request builder to add custom headers or modify the URL
7
        buildRequest: (params) => {
8
            const request = buildTrafficIncidentDetailsRequest(params);
9
            // ... modify request
10
            return request;
11
        }
12
    }
13
);

Error Handling

1
try {
2
    const result = await trafficIncidentDetails({
3
        bbox: [4.728, 52.278, 5.08, 52.479]
4
    });
5

6
    if (result.features.length === 0) {
7
        console.log('No incidents in this area');
8
    }
9
} catch (error) {
10
    // SDKServiceError contains .status (HTTP code) and .service
11
    console.error('Incident Details request failed:', error.message);
12
}

Traffic Incidents - Visualise incidents on an interactive map
Traffic Flow - Display live traffic flow alongside incidents

Routing with Traffic - Plan routes that avoid live incidents
Routing Quickstart - Get started with route planning