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.

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. This helps you control better when you want it to appear on the map.

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}`);

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