Traffic flow module

TrafficFlowModule controls the style's live traffic-flow layers, which colour every road by its speed relative to free flow, from free-flowing to stationary, with closed roads outlined.

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.

• Traffic events across the map (accidents, closures, roadworks) are the Traffic Incidents Module's.
• The incidents along a route are its traffic sections.

Initialization

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

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

• get() adds the trafficFlow style part when the style lacks it, reloading the style; on a custom style without flow it throws.
• It is style-owned: every get() on one map returns the same instance.

Visibility

Flow is hidden until shown. isVisible() reads the visible setting back, false while unset.

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

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

Filtering

filters narrows which roads show flow, at get() or later through updateConfig:

• The fields of filters are one filter: a road shows when it matches every field set.
• Each entry of the any list of filters is an alternative: a road matching any of them shows too.
• A values filter takes show, 'only' or 'all-except' (filterShowModes), and values; it applies only with both set.

Road category

The playground below filters by road category from checkboxes:

// Major roads only
trafficFlowModule.updateConfig({
    filters: { roadCategories: { show: 'only', values: ['motorway', 'motorway_link', 'trunk'] } },
});

// Every road but residential streets
trafficFlowModule.updateConfig({
    filters: { roadSubCategories: { show: 'all-except', values: ['residential'] } },
});

• roadSubCategories takes the street subcategories unclassified, residential and living_street (streetRoadSubCategories), and the service ones parking, driveway and alley (serviceRoadSubCategories).
• Only street and service roads have a subcategory, so a roadSubCategories filter set to 'only' leaves out every other road.
• roadCategories lists the categories as data.

Road closures

trafficFlowModule.updateConfig({ filters: { roadClosures: 'only' } });       // closed roads only
trafficFlowModule.updateConfig({ filters: { roadClosures: 'all-except' } }); // every road but them

Multiple filters

// Motorways, or a closed road of any category
trafficFlowModule.updateConfig({
    filters: {
        roadCategories: { show: 'only', values: ['motorway'] },
        any: [{ roadClosures: 'only' }],
    },
});

Reset filters

trafficFlowModule.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 value while unset.
• A level's outline follows its colour, as the darker rim the style designed.
• The levels are free, slow, queueing, stationary, and closed, the outline of closed roads.

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

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

getStyleColor reads the level colours 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

events.on takes click, hover, long-hover and the other user events; the handler receives the segment as a TrafficFlowModuleFeature.

const unsubscribe = trafficFlowModule.events.on('click', (segment, lngLat) => {
    console.log(segment.properties.relativeSpeed, segment.properties.roadCategory);
});

on returns the function that removes the handler; events.off('click') removes every click handler of the module (Cleanup).

Querying visible features

getRenderedFeatures() returns the flow segments rendered in the current viewport:

const { trafficFlow } = trafficFlowModule.getRenderedFeatures();
const closedRoads = trafficFlow.filter((segment) => segment.properties.roadClosure);
const congested = trafficFlow.filter((segment) => segment.properties.relativeSpeed < 0.5);

What the flow data can and cannot tell you

Orbis traffic flow is vector tiles only, so getRenderedFeatures() 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 (on street and service roads), 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.

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'] }, …]

• The filters knobs set the fields of the filter; the any list of filters is config only. Each show knob goes with its values knob, and unset, nothing is filtered.
• trafficFlowKnobIds lists the ids, TrafficFlowKnobId is their union, and TrafficFlowKnobValueOf<ID> the plain value one takes. The entry shape and its kinds are the modules guide's.
• Not in it: events.
• The traffic config playground builds its flow and incidents controls from the two catalogues and sets each with setKnob.

API reference

TrafficFlowModule, TrafficFlowModuleConfig and TrafficFlowModuleFeature.

Related guides and examples

Related guides

• Traffic overview - Every way the SDK draws traffic
• Traffic incidents module - Live traffic events, with the same road filters

Related examples

• Traffic flow - Flow on every road, shown as the map loads
• Traffic flow playground - Flow filtered by road category, with a popup per segment
• Traffic config playground - Flow and incident presets, with every setting from the knob catalogues
• Map styling playground - The flow colour and width knobs, next to every other look knob of the map
• Traffic flow with bloom - Flow tubes glowing over a mono dark map, through the map effects plugin