Traffic area analytics module

VERSION 0.53.0 PUBLIC PREVIEW

The Traffic Area Analytics Module visualizes historical traffic data for a geographic region on the map. Data is fetched from the TomTom Move Portal API and rendered using one of five visualization modes: 3D or flat hexagonal grids, 3D or flat square grids, or a density heatmap.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { TomTomMap, TrafficAreaAnalyticsModule } from '@tomtom-org/maps-sdk/map';
import { geocodeOne, geometryData, trafficAreaAnalytics } from '@tomtom-org/maps-sdk/services';
import './style.css';
import { API_KEY, MOVE_PORTAL_KEY } from './config';

// (Set your own API key when working in your own environment)
TomTomConfig.instance.put({ apiKey: API_KEY, language: 'en-GB' });

const pastDateRange = (): { startDate: string; endDate: string } => {
    const end = new Date();
    end.setDate(end.getDate() - 3);
    const start = new Date();
    start.setDate(start.getDate() - 9);
    return { startDate: start.toISOString().slice(0, 10), endDate: end.toISOString().slice(0, 10) };
};

(async () => {
    const cityName = 'Amsterdam, Netherlands';
    const place = await geocodeOne(cityName);

    // Init map immediately so it loads while analytics are being fetched
    const map = new TomTomMap({
        mapLibre: { container: 'sdk-map', bounds: place.bbox, fitBoundsOptions: { padding: 40, pitch: 45 } },
    });

    // Fetch geometry then kick off analytics — runs in parallel with map initialization
    const analyticsPromise = geometryData({ geometries: [place] })
        .then(({ features }) => features[0]?.geometry)
        .then((geometry) =>
            trafficAreaAnalytics({
                apiKey: MOVE_PORTAL_KEY,
                name: cityName,
                ...pastDateRange(),
                metrics: ['speed', 'congestionLevel', 'freeFlowSpeed', 'travelTime'],
                functionalRoadClasses: 'all',
                hours: 'all',
                geometry,
            }),
        );

    const [analyticsModule, analytics] = await Promise.all([TrafficAreaAnalyticsModule.create(map), analyticsPromise]);

    await analyticsModule.show(analytics);
})();

Open Sandbox

Initialization

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

3
const map = new TomTomMap({ mapLibre: { container: 'map' } });
4
const analyticsModule = await TrafficAreaAnalyticsModule.create(map);

Configure the module at initialization time using a config object:

1
const analyticsModule = await TrafficAreaAnalyticsModule.create(map, {
2
    displayMode: 'hexgrid-3d',
3
    activeMetric: 'congestionLevel',
4
    metricConfig: {
5
        congestionLevel: { color: 'trafficLight' },
6
    },
7
});

Fetching and displaying data

Fetch area analytics data using the trafficAreaAnalytics service and pass the response directly to show().

1
import { geocodeOne, geometryData, trafficAreaAnalytics } from '@tomtom-org/maps-sdk/services';
2
import { bboxFromGeoJSON } from '@tomtom-org/maps-sdk/core';
3

4
// 1. Geocode a city to get its boundary
5
const place = await geocodeOne('Amsterdam, Netherlands');
6
const boundary = await geometryData({ geometries: [place] });
7
const regionGeometry = boundary.features[0].geometry;
8

9
// 2. Fetch analytics for the last 7 days
10
const endDate = new Date();
11
endDate.setDate(endDate.getDate() - 2); // API requires at least 2 days ago
12
const startDate = new Date(endDate);
13
startDate.setDate(startDate.getDate() - 6);
14
const fmt = (d) => d.toISOString().slice(0, 10);
15

16
const analytics = await trafficAreaAnalytics({
17
    apiKey: MOVE_PORTAL_KEY,
18
    name: 'Amsterdam, Netherlands',
19
    startDate: fmt(startDate),
20
    endDate: fmt(endDate),
21
    metrics: 'all',
22
    functionalRoadClasses: 'all',
23
    hours: 'all',
24
    geometry: regionGeometry,
25
});
26

27
// 3. Display on the map
28
await analyticsModule.show(analytics);

To remove data from the map:

1
await analyticsModule.clear();

Visualization modes

Five modes are available, set via displayMode at init time or changed at runtime with setMode():

Mode	Description
`'hexgrid-3d'`	3D extruded hexagonal cells colored and raised by metric value (default)
`'hexgrid-2d'`	Flat hexagonal cells colored by metric value
`'square-3d'`	3D extruded square cells colored and raised by metric value
`'square-2d'`	Flat square cells colored by metric value
`'heatmap'`	MapLibre density heatmap from tile center points

Switch modes at any time using setMode():

1
analyticsModule.setMode('heatmap');
2
analyticsModule.setMode('hexgrid-2d');
3
analyticsModule.setMode('square-3d');

Metrics

Five metrics are available to drive color and extrusion height. Set the active one via activeMetric. Per-metric style settings (color, height, filters) are configured via metricConfig.

Metric	Description
`'congestionLevel'`	Percentage increase in travel time above free-flow conditions (default active metric)
`'speed'`	Average vehicle speed in km/h
`'travelTime'`	Average travel time per 10 km in minutes
`'freeFlowSpeed'`	Average speed under uncongested conditions in km/h
`'networkLength'`	Total road length within each tile in metres — useful as a road density indicator

1
analyticsModule.setMetric('speed');
2
analyticsModule.setMetric('travelTime');
3
analyticsModule.setMetric('freeFlowSpeed');

You can also pre-configure multiple metrics at init time:

1
const analyticsModule = await TrafficAreaAnalyticsModule.create(map, {
2
    activeMetric: 'congestionLevel',
3
    metricConfig: {
4
        congestionLevel: { color: 'trafficLight' },
5
        speed: { color: 'heat' },
6
        travelTime: { height: { maxHeightMeters: 300 } },
7
    },
8
});

Color

Color configuration is per-metric and set under metric.[metricKey].color. You can use a preset theme name or provide custom color stops.

Preset themes

1
// Apply a preset theme to all metrics
2
analyticsModule.setColor('trafficLight'); // green → amber → red (default)
3
analyticsModule.setColor('heat');         // blue → orange → red
4
analyticsModule.setColor('monochrome');   // light grey → dark grey
5
analyticsModule.setColor('viridis');      // purple → blue → green → yellow
6
analyticsModule.setColor('plasma');       // purple → magenta → orange → yellow

Custom color stops

Provide an AreaAnalyticsColorStopsConfig object with a valueType and stops array.

'raw' (default) — stop value fields are actual data values:

1
analyticsModule.setColor({
2
    valueType: 'raw',
3
    stops: [
4
        { value: 0,   color: '#2dc653' },  // 0% congestion
5
        { value: 30,  color: '#f5a623' },  // 30% congestion
6
        { value: 100, color: '#e03030' },  // 100% congestion
7
    ],
8
});

'relativeToPredefinedRangePCT' — stop value fields are 0–100 percentages relative to the SDK’s predefined metric ranges (congestion 0–100, speed 0–120 km/h, travelTime 0–20 s/km). Useful for consistent coloring across datasets:

1
analyticsModule.setColor({
2
    valueType: 'relativeToPredefinedRangePCT',
3
    stops: [
4
        { value: 0,   color: '#2dc653' },  // 0% of predefined range
5
        { value: 50,  color: '#f5a623' },  // 50% of predefined range
6
        { value: 100, color: '#e03030' },  // 100% of predefined range
7
    ],
8
});

'relativeToActualRangePCT' — stop value fields are 0–100 percentages relative to the live data range actually present in the loaded tiles (0 % = loaded minimum, 100 % = loaded maximum). Maximises contrast regardless of absolute values:

1
analyticsModule.setColor({
2
    valueType: 'relativeToActualRangePCT',
3
    stops: [
4
        { value: 0,   color: '#2dc653' },  // 0% of loaded range
5
        { value: 50,  color: '#f5a623' },  // 50% of loaded range
6
        { value: 100, color: '#e03030' },  // 100% of loaded range
7
    ],
8
});

Pass undefined to revert to the default 'trafficLight' theme:

1
analyticsModule.setColor(undefined);

For speed, the color order is automatically inverted so that slow speeds render as “bad” (red) and fast speeds as “good” (green).

Height

Height (extrusion) configuration is per-metric under metric.[metricKey].height. Use setHeight() to update the active metric’s height config.

1
// Predefined range (default): metric normalized to SDK predefined range, visual max = maxHeightMeters
2
analyticsModule.setHeight({ maxHeightMeters: 200 });
3

4
// Set a minimum height floor
5
analyticsModule.setHeight({ maxHeightMeters: 100, minHeightMeters: 10 });
6

7
// Current range: normalizes to live data range — maximises contrast for whatever data is loaded
8
analyticsModule.setHeight({ maxHeightMeters: 150, scaleMode: 'currentRange' });
9

10
// Raw: scaleFactor is multiplied directly with the raw metric value to obtain height in meters
11
analyticsModule.setHeight({ scaleMode: 'raw', scaleFactor: 10 });

Filtering

Filter visible tiles by value range for the active metric using filter(). Only tiles within the given range will be rendered.

1
// Show only tiles with congestion ≥ 50
2
analyticsModule.filter({ min: 50 });
3

4
// Show only tiles within a range
5
analyticsModule.filter({ min: 20, max: 80 });
6

7
// Clear the filter
8
analyticsModule.clearFilter();
9
analyticsModule.filter(undefined); // equivalent

Region boundary

When show() is called, all region polygons in the analytics response are rendered alongside the analytics cells as a subtle fill with an outline. Customize their appearance using regionPolygon:

1
const analyticsModule = await TrafficAreaAnalyticsModule.create(map, {
2
    regionPolygon: {
3
        color: '#0052a5',      // fill and outline color (default: '#000000')
4
        fillOpacity: 0.08,     // default: 0
5
        outlineOpacity: 1.0,   // default: 0.5
6
        outlineWidth: 3,       // default: 2
7
    }
8
});

Layer positioning

Control where analytics layers are placed in the map’s rendering stack using beforeLayerConfig. Use 'top' to draw above all layers, or supply a well-known style layer ID to insert the analytics layers below it.

1
// Place below all labels (default behavior)
2
const analyticsModule = await TrafficAreaAnalyticsModule.create(map, {
3
    beforeLayerConfig: { heatmap: 'lowestLabel' },
4
});
5

6
// Place everything on top
7
const analyticsModule = await TrafficAreaAnalyticsModule.create(map, {
8
    beforeLayerConfig: {
9
        heatmap: 'top',
10
        hexgrid: { flat2D: 'top', extrusion3D: 'top' },
11
    },
12
});
13

14
// Reposition after initialization
15
analyticsModule.moveBeforeLayer({
16
    hexgrid: { flat2D: 'lowestLabel', extrusion3D: 'lowestPlaceLabel' },
17
});

Visibility

Control overall layer visibility:

1
// Hidden at startup
2
const analyticsModule = await TrafficAreaAnalyticsModule.create(map, { visible: false });
3

4
// Toggle later
5
analyticsModule.setVisible(true);
6

7
// Check current state
8
console.log(analyticsModule.isVisible()); // true | false

Events

Listen to click and hover events on hexgrid and square cells. Events fire for whichever mode is currently active.

1
analyticsModule.events.on('click', (feature, lngLat) => {
2
    console.log('Congestion:', feature.properties.congestionLevel);
3
    console.log('Speed:', feature.properties.speed);
4
});
5

6
analyticsModule.events.on('hover', (feature) => {
7
    console.log('Hovered cell:', feature.properties);
8
});
9

10
analyticsModule.events.on('long-hover', (feature) => {
11
    console.log('Long-hovered cell:', feature.properties);
12
});
13

14
// Remove a specific listener
15
analyticsModule.events.off('click');

Use events.on('hover') to build a hover tooltip:

1
import { Popup } from 'maplibre-gl';
2

3
const popup = new Popup({ closeButton: false, anchor: 'left', offset: 12 });
4

5
analyticsModule.events.on('hover', (feature, lngLat) => {
6
    if (!feature) { popup.remove(); return; }
7
    const { congestionLevel, speed } = feature.properties;
8
    popup
9
        .setLngLat(lngLat)
10
        .setHTML(`<strong>Congestion:</strong> ${congestionLevel ?? 0}%<br/><strong>Speed:</strong> ${speed ?? 0} km/h`)
11
        .addTo(map.mapLibreMap);
12
});
13

14
map.mapLibreMap.getCanvas().addEventListener('mouseleave', () => popup.remove());

Config change events

Subscribe to config changes emitted whenever a setter is called:

1
const unsub = analyticsModule.events.on('config-change', (config) => {
2
    console.log('Active metric:', config?.activeMetric);
3
});
4
// Later: unsub();

Querying shown features

Use getShown() to access the GeoJSON feature collections currently rendered for each visualization mode:

1
const { heatmap, hexgrid, square } = analyticsModule.getShown();
2
console.log(`Hexagonal cells in view: ${hexgrid.features.length}`);

API reference

For complete documentation of all properties, methods, and types, see the TrafficAreaAnalyticsModule API Reference.

Traffic overview

Traffic Overview - Overview of all traffic visualization options

Traffic Flow Module - Real-time traffic speed conditions across the road network
Traffic Incidents Module - Real-time traffic events and incidents

Traffic Area Analytics - Basic area analytics with a geocoded location
Traffic Area Analytics Playground - Full-featured playground with city search, legend, and tooltips
Traffic Area Analytics Config Playground - 2D/3D mode toggle and custom color pickers