TomTom Maps SDK for JavaScript
This is the documentation of version 0.63.0. Go to the latest version, 1.0.0-rc.5.

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, for which roads, and how they look — visibility, filters, and the colour of each flow level and the line width. See Who owns what.

Looking for something else?

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, and read the setting back with isVisible(), which is false until something shows the flow.

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

Filtering

A filter can be applied either during module initialization or later through updateConfig.

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

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

Road category

Display traffic flow only for specific road types. The playground below filters by road category from checkboxes:

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

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

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

Available Road Categories:

Available Road Subcategories:

Road closures

Display or exclude road closures:

// Show only road closures
trafficFlow.updateConfig({
    filters: { roadClosures: 'only' }
});

// Exclude road closures
trafficFlow.updateConfig({
    filters: { roadClosures: 'all-except' }
});

Multiple filters

The criteria of one filter all apply. any adds further filters a road may match instead:

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

Reset filters

Remove all filters and show all traffic flow:

trafficFlow.updateConfig({ filters: undefined });

Appearance

colors recolours each flow level, and widthFactor (0.5 to 2) multiplies the width of the flow lines. Each restyles the style's own flow layers and reads the style's own value while unset; the outline of a level follows its colour, as the darker rim the style designed.

const trafficFlowModule = await TrafficFlowModule.get(map, {
    visible: true,
    colors: { slow: '#f59e0b', stationary: '#7f1d1d' },
    widthFactor: 1.5,
});
setKnob(trafficFlowModule, trafficFlowKnobCatalogue, 'colors.free', '#16a34a');

The levels are free, slow, queueing, stationary, and closed, the outline of closed roads. getStyleColor reads them by their map-wide ids, such as traffic.flow.colors.slow, with or without the module, and so does the map effects plugin's bloom scope.

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.

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

Every setting as data

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

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

// [{ id: 'visible', kind: 'toggle', description: '…', default: false },
//  { id: 'filters.roadCategories.show', kind: 'enum', description: '…', options: ['only', 'all-except'] },
//  { id: 'filters.roadCategories.values', kind: 'enums', description: '…', options: ['motorway', …, 'track'] }, …]
Id Kind
visible toggle, false by default
filters.roadCategories.show, filters.roadSubCategories.show, filters.roadClosures enum: only or all-except
filters.roadCategories.values enums: the road categories
filters.roadSubCategories.values enums: the street, then the service road subcategories
colors.free, colors.slow, colors.queueing, colors.stationary, colors.closed colour, the style's own while unset
widthFactor factor 0.5–2, 1 by default

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

Related traffic modules

Related examples