Traffic flow module

The Traffic Flow Module controls the map layers that display real-time traffic speed conditions across the entire road network using color-coded road segments. Green indicates free-flowing traffic, yellow/orange represents moderate speeds, and red shows congestion. Dark gray indicates road closures.

What this module owns: whether the style's traffic-flow layers are shown, and for which roads — visibility and filters. The colours of each flow level and the line width are Styling module knobs (traffic.flow.*). See Who owns what.

Looking for something else?

• For traffic events (accidents, closures, construction) across the map, see Traffic Incidents Module
• For traffic incidents along a specific route, see Routing Module

Initialization

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

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

Visibility

Traffic flow is 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 it visible during initialization:

const trafficFlowModule = await TrafficFlowModule.get(map, { visible: true });

You can change visibility later using the setVisible method.

trafficFlowModule.setVisible(true);

Filtering

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

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

// Apply or update filter later
trafficFlowModule.filter(...);

Road category

Display traffic flow only for specific road types:

// Show only major highways
trafficFlowModule.filter({
    any: [{
        roadCategories: {
            show: 'only',
            values: ['motorway', 'trunk']
        }
    }]
});

// Hide local streets
trafficFlow.filter({
    any: [{
        roadCategories: {
            show: 'all-except',
            values: ['street']
        }
    }]
});

// Show only major local roads within tertiary category
trafficFlow.filter({
    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

Road closures

Display or exclude road closures:

// Show only road closures
trafficFlow.filter({
    any: [{ showRoadClosures: 'only' }]
});

// Exclude road closures
trafficFlow.filter({
    any: [{ showRoadClosures: 'all-except' }]
});

Multiple filters

Combine multiple filter criteria using "any" logic:

// Show motorways OR road closures
trafficFlow.filter({
    any: [
        { roadCategories: { show: 'only', values: ['motorway'] } },
        { showRoadClosures: 'only' }
    ]
});

Reset filters

Remove all filters and show all traffic flow:

trafficFlow.filter(undefined);

Events

Handle user interactions with traffic flow segments:

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

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

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

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

Querying visible features

Use getShown() to retrieve all traffic flow features currently rendered in the visible map area:

const shown = trafficFlowModule.getShown();
console.log(`Visible flow segments: ${shown.trafficFlow.length}`);
shown.trafficFlow.forEach(segment => {
    console.log('Road segment:', segment.properties);
});

This is useful for analyzing traffic conditions in the current viewport:

const { trafficFlow } = trafficFlowModule.getShown();
const closedRoads = trafficFlow.filter(segment => segment.properties.roadClosure);
console.log(`Road closures in view: ${closedRoads.length}`);

What the flow data can and cannot tell you

Orbis traffic flow is vector tiles only, so getShown() is the whole of flow as data: there is no service for a road, a point or an area.

• Carried: relativeSpeed (0 to 1, current speed relative to free flow), roadCategory, roadSubcategory, roadClosure, leftHandTraffic and displayClass.
• Empty with the standard styles: absoluteSpeed, partOfTwoWayRoad and openlr. The styles don't request the absolute_speed, part_of_two_way_road or openlr tile tags; a custom style's flow source can.
• On no Orbis flow tile: free-flow speed, travel time, delay in seconds and confidence.
• Scope: the current viewport and zoom. A segment crossing a tile boundary appears once per tile.

For historical speed and congestion aggregated over an area, use the Traffic Area Analytics service.

API reference

For complete documentation of all Traffic Flow Module properties, methods, and types, see the TrafficFlowModule 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 Incidents Module - Display real-time traffic events and incidents
• Routing Module - Display routes with traffic incidents along the path

Related examples

• Traffic Flow - Interactive traffic flow visualization with filtering
• Traffic Config Playground - Explore traffic configuration options
• Traffic flow with bloom - Flow tubes glowing over a mono dark map, through the map effects plugin