TomTom Maps SDK for JavaScript
This is the documentation of version 0.61.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, 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?

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 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:

Available Road Subcategories:

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.

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.any.0.roadCategories.show', kind: 'enum', description: '…', options: ['only', 'all-except'] },
//  { id: 'filters.any.0.roadCategories.values', kind: 'enums', description: '…', options: ['motorway', …, 'track'] }, …]
Id Kind
visible toggle, false by default
filters.any.0.roadCategories.show, filters.any.0.roadSubCategories.show, filters.any.0.showRoadClosures enum: only or all-except
filters.any.0.roadCategories.values enums: the road categories
filters.any.0.roadSubCategories.values enums: the street, then the service road subcategories

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