Traffic incidents module

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.

What this module owns: whether the style's incident layers and icons are shown, and which incidents — visibility and filters. The colour of each severity and the line width are Styling module knobs (traffic.incidents.*). Incidents you fetched yourself are drawn by the Traffic Incident Details Module instead. See Who owns what.

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
• For rendering incidents you fetched via the trafficIncidentDetails() REST service as a developer-controlled overlay, see Traffic Incident Details Module

Initialization

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

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

Visibility

Traffic incidents are hidden by default: the style parts the SDK adds — traffic flow, traffic incidents and the hillshade — are hidden until you show them.

You can make them visible during initialization:

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

You can change visibility later using the setVisible method, and read the setting back with isVisible(), which is false until something shows the incidents.

trafficIncidentsModule.setVisible(true);
trafficIncidentsModule.isVisible(); // true

Icon visibility

Icons can be shown or hidden separately from incident areas, so you can show only the icons, or only the lines, at any time. They always show the same incidents as the lines: the module's filters apply to both.

• icons.visible, which setIconsVisible sets, overrides visible for the icons. isIconsVisible() reads it back and, while it is unset, returns isVisible().
• setVisible clears icons.visible, so the icons follow visible again. To show only the icons, configure { visible: false, icons: { visible: true } }, or call setVisible(false) and then setIconsVisible(true).

// Initialize with the lines shown and the icons hidden
const trafficIncidentsModule = await TrafficIncidentsModule.get(map, {
    visible: true,
    icons: {
        visible: false,
    },
});
trafficIncidentsModule.isIconsVisible(); // false

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

// Show only the icons
trafficIncidentsModule.setVisible(false);
trafficIncidentsModule.setIconsVisible(true);
trafficIncidentsModule.isIconsVisible(); // true

// setVisible clears icons.visible: the icons follow visible again
trafficIncidentsModule.setVisible(true);
trafficIncidentsModule.getConfig(); // { visible: true }

isIconsVisible() reports the setting. To read whether a style layer itself is shown, use map.mapLibreMap.getLayoutProperty(layerId, 'visibility').

Filtering

A filter can be applied either during module initialization or later through updateConfig. It narrows the incident lines and their icons alike.

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

// Apply or update filter later
trafficIncidentsModule.updateConfig({ filters: ... });

Incident category

Display only specific types of incidents:

// Show only accidents and road closures
trafficIncidentsModule.updateConfig({
    filters: {
        any: [{
            incidentCategories: {
                show: 'only',
                values: ['accident', 'road-closed']
            }
        }]
    }
});

// Hide weather-related incidents
incidents.updateConfig({
    filters: {
        any: [{
            incidentCategories: {
                show: 'all-except',
                values: ['rain', 'fog', 'frost', 'wind']
            }
        }]
    }
});

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. The playground below filters by magnitude from checkboxes:

// Show moderate and major delays
incidents.updateConfig({
    filters: {
        any: [{
            magnitudes: {
                show: 'only',
                values: ['major', 'moderate']
            }
        }]
    }
});

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:

// Show incidents with at least 5 minutes delay
incidents.updateConfig({
    filters: {
        any: [{
            delays: {
                mustHaveDelay: true,
                minDelayMinutes: 5
            }
        }]
    }
});

Road category

Display incidents only on specific road types:

// Show incidents only on highways
incidents.updateConfig({
    filters: {
        any: [{
            roadCategories: {
                show: 'only',
                values: ['motorway', 'trunk']
            }
        }]
    }
});

// Show incidents only on major local roads within tertiary category
incidents.updateConfig({
    filters: {
        any: [{
            roadCategories: {
                show: 'only',
                values: ['tertiary']
            },
            roadSubCategories: {
                show: 'only',
                values: ['major_local']
            }
        }]
    }
});

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:

// Show major accidents OR road closures
incidents.updateConfig({
    filters: {
        any: [
            {
                incidentCategories: { show: 'only', values: ['accident'] },
                magnitudes: { show: 'only', values: ['major'] }
            },
        ]
    }
});

Reset filters

Remove all filters and show all incidents:

incidents.updateConfig({ filters: undefined });

Events

Handle user interactions with traffic incidents:

// Click events
incidents.events.on('click', (feature) => {
    ...
});

// Hover events
incidents.events.on('hover', (feature) => {
    ...
});

// Long hover events
incidents.events.on('long-hover', (feature) => {
    ...
});

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

Querying visible features

Use getShown() to retrieve all traffic incident features currently rendered in the visible map area, including both incident areas/lines and icon markers:

const shown = trafficIncidentsModule.getShown();
console.log(`Visible incidents: ${shown.trafficIncidents.length}`);
shown.trafficIncidents.forEach(incident => {
    console.log('Incident:', incident.properties.category, '-', incident.properties.magnitudeOfDelay);
});

Filter and analyze visible incidents by category or severity:

const { trafficIncidents } = trafficIncidentsModule.getShown();
const accidents = trafficIncidents.filter(
    incident => incident.properties.category === 'accident'
);
console.log(`Accidents in view: ${accidents.length}`);

Every setting as data

trafficIncidentsKnobCatalogue lists the module's plain-valued settings with their kind, range or options and, where one value holds everywhere, their default, readable with no map loaded:

import { trafficIncidentsKnobCatalogue } from '@tomtom-org/maps-sdk/map';

// [{ id: 'visible', kind: 'toggle', description: '…', default: false },
//  { id: 'icons.visible', kind: 'toggle', description: '…' }, …,
//  { id: 'filters.any.0.magnitudes.values', kind: 'enums', description: '…', options: ['unknown', 'minor', 'moderate', 'major', 'indefinite'] }, …]

• The filters.any.0 knobs set the first of the filter alternatives; an incident matching any further alternative, which only the configuration sets, shows too. Each show knob goes with its values knob, and unset, nothing is filtered.
• trafficIncidentsKnobIds lists the ids, TrafficIncidentsKnobId is their union, and TrafficIncidentsKnobValueOf<ID> the plain value one takes. The entry shape and its kinds are the modules guide's.
• Not in it: events. The look of the incidents is the styling catalogue's traffic.incidents.* knobs.
• The traffic config playground builds its flow and incidents controls, the filters included, from the two catalogues and sets each with setKnob.

API reference

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

Related guides and examples

Traffic overview

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

Related traffic modules

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

Related examples

• Traffic Incidents - Interactive traffic incidents visualization with filtering
• Traffic Config Playground - Explore traffic configuration options
• Traffic incidents playground - Incidents filtered by severity, with a popup per incident
• Map styling playground - The traffic.incidents.* colour and width knobs