Traffic flow module

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

The module owns the visibility, filters and look of the style's traffic-flow layers, including the colour of each flow level and the line width. See Who owns what.

To show live flow over a whole city, call get with visible: true. Move the center to see another city's traffic:

• The Traffic Incidents Module shows traffic events (accidents, closures, roadworks) across the map.
• 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);

• If the style lacks the trafficFlow style part, get() adds it and reloads the style.
• It is style-owned, so every get() on one map returns the same instance.

Visibility

Flow is hidden until you show it. isVisible() returns the visible setting, false by default.

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

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

Filtering

Set filters at get() or later through updateConfig to narrow which roads show flow.

• The fields of filters form one filter. A road must match every field you 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 when both are set.

Road category

The playground below filters by road category with 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. By default, the style's value applies.
• A level's outline follows its colour, as the darker rim the style designed.
• The levels are free, slow, queueing and stationary, plus closed for 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 and the bloom scope of the map effects plugin read the level colours by their map-wide ids, such as traffic.flow.colors.slow, with or without the module.

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 comes only as vector tiles. There is no service for a road, a point or an area, so getRenderedFeatures() is your only source of flow data.

• Tiles carry relativeSpeed (0 to 1, current speed relative to free flow), absoluteSpeed (current speed in km/h), openlr (the section's OpenLR location reference), roadCategory, roadSubcategory (on street and service roads), roadClosure, leftHandTraffic and displayClass.
• partOfTwoWayRoad is true on a section that covers both directions of a two-way road, and absent otherwise.
• No Orbis flow tile has free-flow speed, travel time, delay in seconds or confidence.
• Results cover what is drawn in the current viewport and zoom, so a hidden module returns none. 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 any default that holds. You can read it 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. If you leave them unset, nothing is filtered.
• trafficFlowKnobIds lists the ids, TrafficFlowKnobId is their union, and TrafficFlowKnobValueOf<ID> is the plain value one takes. The modules guide describes the entry shape and its kinds.
• It leaves out 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