Traffic Incidents Module

VERSION 0.41.1 PUBLIC PREVIEW

The Traffic Incidents Module controls the map layers that display real-time traffic events, such as accidents, road closures, construction, and weather disruptions. Events are displayed across the entire map area and each incident shows its type, severity, affected road segments, and expected delay impact.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { TomTomMap, TrafficIncidentsModule } from '@tomtom-org/maps-sdk/map';
import './style.css';
import { API_KEY } from './config';

// (Set your own API key when working in your own environment)
TomTomConfig.instance.put({ apiKey: API_KEY, language: 'en-US' });

(async () => {
    const map = new TomTomMap({
        mapLibre: {
            container: 'sdk-map',
            center: [2.34281, 48.85639],
            zoom: 12,
        },
    });
    await TrafficIncidentsModule.get(map, { visible: true });
})();

Open Sandbox

Looking for something else?

For traffic speed conditions (color-coded congestion) across the map, see Traffic Flow Module
For traffic incidents along a specific route, see Routing Module

Initialization

1
import { TomTomMap, TrafficIncidentsModule } from '@tomtom-org/maps-sdk/map';
2

3
const map = new TomTomMap( { mapLibre: { container: 'map' } } );
4
const trafficIncidentsModule = await TrafficIncidentsModule.get(map);

Visibility

Traffic incidents are hidden by default. This helps you control better when you want them to appear on the map.

You can make them visible during initialization:

1
const trafficIncidentsModule = await TrafficIncidentsModule.get(map, { visible: true });

You can change visibility later using the setVisible method.

1
trafficIncidentsModule.setVisible(true);

Icon Visibility

Icons can be controlled separately from incident areas. This allows you to show only the icons, or only the lines, at any time.

1
// Initialize with visibility set in the configuration
2
const trafficIncidentsModule = await TrafficIncidentsModule.get(map, {
3
    icons: {
4
        visible: false,
5
    },
6
});
7

8
// Show/hide incident icons but keep incident areas visible
9
trafficIncidentsModule.setIconsVisible(true);
10
trafficIncidentsModule.setIconsVisible(false);
11

12
// Check icon visibility
13
if (trafficIncidentsModule.anyIconLayersVisible()) {
14
    console.log('Incident icons are visible');
15
}

Filtering

A filter can be applied either during module initialization or later using the filter method.

1
// Initialize with filter
2
const trafficIncidentsModule = await TrafficIncidentsModule.get(map, {
3
    filters: ...,
4
});
5

6
// Apply or update filter later
7
trafficIncidentsModule.filter(...);

Incident Category

Display only specific types of incidents:

1
// Show only accidents and road closures
2
trafficIncidentsModule.filter({
3
    any: [{
4
        incidentCategories: {
5
            show: 'only',
6
            values: ['accident', 'road_closed']
7
        }
8
    }]
9
});
10

11
// Hide weather-related incidents
12
incidents.filter({
13
    any: [{
14
        incidentCategories: {
15
            show: 'all_except',
16
            values: ['rain', 'fog', 'ice', 'wind']
17
        }
18
    }]
19
});

Available Incident Categories:

accident - Traffic accidents
road_closed - Complete road closures
lane_closed - Lane closures
road_works - Construction and maintenance
jam - Traffic jams
fog, rain, ice, wind, flooding - Weather conditions
dangerous_conditions - Hazardous road conditions
broken_down_vehicle - Vehicle breakdowns
unknown - Incidents with unknown type

Severity

Filter incidents based on their delay magnitude:

1
// Show moderate and major delays
2
incidents.filter({
3
    any: [{
4
        magnitudes: {
5
            show: 'only',
6
            values: ['major', 'moderate']
7
        }
8
    }]
9
});

Available Magnitudes:

minor - Small delays
moderate - Moderate delays
major - Significant delays
indefinite - Road closures with no estimated delay
unknown - Unknown or no delay information

Delay Duration

Filter incidents by minimum delay:

1
// Show incidents with at least 5 minutes delay
2
incidents.filter({
3
    any: [{
4
        delays: {
5
            mustHaveDelay: true,
6
            minDelayMinutes: 5
7
        }
8
    }]
9
});

Road Category

Display incidents only on specific road types:

1
// Show incidents only on highways
2
incidents.filter({
3
    any: [{
4
        roadCategories: {
5
            show: 'only',
6
            values: ['motorway', 'trunk']
7
        }
8
    }]
9
});
10

11
// Show incidents only on major local roads within tertiary category
12
incidents.filter({
13
    any: [{
14
        roadCategories: {
15
            show: 'only',
16
            values: ['tertiary']
17
        },
18
        roadSubCategories: {
19
            show: 'only',
20
            values: ['major_local']
21
        }
22
    }]
23
});

Available Road Categories:

motorway - Major highways
trunk - Major roads
primary - Primary roads
secondary - Secondary roads
tertiary - Tertiary roads
street - Local streets

Available Road Subcategories:

tertiary
- connecting - Roads connecting different areas
- major_local - Major roads within local areas
street
- local - Standard local streets
- minor_local - Minor residential streets

Multiple Filters

Combine multiple filter criteria:

1
// Show major accidents OR road closures
2
incidents.filter({
3
    any: [
4
        {
5
            incidentCategories: { show: 'only', values: ['accident'] },
6
            magnitudes: { show: 'only', values: ['major'] }
7
        },
8
    ]
9
});

Separate Icon and Area Filters

Apply different filters to icons and incident areas:

1
// Show all incidents on highways
2
const incidentFilter = {
3
    any: [{
4
        roadCategories: { show: 'only', values: ['motorway', 'trunk'] }
5
    }]
6
};
7

8
// But only show icons for major incidents
9
const iconFilter = {
10
    any: [{
11
        magnitudes: { show: 'only', values: ['major'] }
12
    }]
13
};
14

15
incidents.filter(incidentFilter, iconFilter);

Reset Filters

Remove all filters and show all incidents:

1
incidents.filter(undefined);

Events

Handle user interactions with traffic incidents:

1
// Click events
2
incidents.events.on('click', (feature) => {
3
    ...
4
});
5

6
// Hover events
7
incidents.events.on('hover', (feature) => {
8
    ...
9
});
10

11
// Long hover events
12
incidents.events.on('long-hover', (feature) => {
13
    ...
14
});
15

16
// Remove event listeners
17
incidents.events.off('click', handler);

API Reference

For complete documentation of all Traffic Incidents Module properties, methods, and types, see the TrafficIncidentsModule API Reference .

Traffic Overview

Traffic Overview - Overview of all traffic visualization options including flow, incidents, and route-specific traffic

Traffic Flow Module - Display real-time traffic speed conditions
Routing Module - Display routes with traffic incidents along the path

Traffic Incidents - Interactive traffic incidents visualization with filtering
Traffic Config Playground - Explore traffic configuration options