Class TrafficAreaAnalyticsModule

Traffic Area Analytics visualization module.

Renders area-analytics data on the map in one of five modes:

hexgrid-3d — 3D extruded hexagonal cells coloured and raised by the active metric (default)
hexgrid-2d — Flat hexagonal cells coloured by the active metric
square-3d — 3D extruded square cells coloured and raised by the active metric
square-2d — Flat square cells coloured by the active metric
heatmap — a MapLibre density-heatmap layer built from tile-centre points

The actual region boundary is always rendered alongside the analytics cells.

Remarks

Quick start:

import { TrafficAreaAnalyticsModule } from '@tomtom-org/maps-sdk/map';
import { trafficAreaAnalytics } from '@tomtom-org/maps-sdk/services';

const module = await TrafficAreaAnalyticsModule.get(map, {
  displayMode: 'hexgrid-3d',
  metric: { active: 'congestionLevel' },
});
const analytics = await trafficAreaAnalytics({ ... });
await module.show(analytics);

Hierarchy (View Summary)

AbstractMapModule<AreaAnalyticsSourcesWithLayers, TrafficAreaAnalyticsConfig>
- TrafficAreaAnalyticsModule

Index

Accessors

events sourceAndLayerIDs

Methods

applyConfig clear clearFilter filter getConfig getShown isVisible moveBeforeLayer resetConfig setColor setHeight setMetric setMode setVisible show waitUntilModuleReady get

Accessors

events

get events(): CombinedEvents<
    AreaAnalyticsTileFeature,
    TrafficAreaAnalyticsConfig,
    TrafficAreaAnalytics,
>
Event interface for the hexgrid and square layers.

Supports feature-interaction events (hover, click, contextmenu, long-hover) as well as module lifecycle events (config-change, shown-features) — all through the same events.on(type, handler) surface.

Returns CombinedEvents<
    AreaAnalyticsTileFeature,
    TrafficAreaAnalyticsConfig,
    TrafficAreaAnalytics,
>
Example
```
module.events.on('hover', (feature, lngLat) => {
  console.log(feature.properties.congestionLevel);
});

const unsub = module.events.on('config-change', (config) => {
  console.log('Config updated:', config);
});

module.events.on('shown-features', (data) => {
  console.log('Analytics data shown:', data);
});
```

sourceAndLayerIDs

get sourceAndLayerIDs(): Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>
Gets the source and layer identifiers for all sources managed by this module.

This property provides access to the MapLibre source and layer IDs that were created and are managed by this module. These IDs can be used to interact directly with MapLibre's API or to identify which layers belong to this module.

Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>
A record mapping each source name to its corresponding source ID and layer IDs. Each entry contains the MapLibre source identifier and an array of layer identifiers associated with that source.
Remarks
The returned IDs are useful when you need to:
- Directly manipulate layers using MapLibre's native API
- Identify which layers on the map belong to this module
- Set layer ordering or positioning relative to other layers
- Access source or layer properties through MapLibre methods
Example
```
const ids = myModule.sourceAndLayerIDs;
console.log(ids);
// {
//   mySource: {
//     sourceID: 'my-source-id',
//     layerIDs: ['layer-1', 'layer-2']
//   }
// }

// Use with MapLibre API
const map = myModule.mapLibreMap;
ids.mySource.layerIDs.forEach(layerId => {
  map.setLayoutProperty(layerId, 'visibility', 'visible');
});
```
Inherited from AbstractMapModule.sourceAndLayerIDs

Methods

applyConfig

applyConfig(config: TrafficAreaAnalyticsConfig | undefined): void
Applies a configuration to this module.

This method updates the module's behavior and appearance based on the provided configuration. The configuration is stored internally and will be automatically reapplied if the map style changes.
Parameters
- config: TrafficAreaAnalyticsConfig | undefined
  The configuration object to apply to the module. Pass undefined to reset the configuration to default values.
Returns void
Remarks
When a configuration is applied, the module updates its visual representation and behavior accordingly. The configuration persists across map style changes, ensuring consistent module behavior even when the map's base style is modified.
Example
```
// Apply a new configuration
myModule.applyConfig({ visible: true, opacity: 0.8 });

// Reset to default configuration
myModule.applyConfig(undefined);
```
See
- resetConfig for a convenience method to reset configuration
- getConfig to retrieve the current configuration
Inherited from AbstractMapModule.applyConfig

clear

clear(): Promise<void>
Removes all area analytics data from the map.

Returns Promise<void>

clearFilter

clearFilter(
    metrics?: (
        | "speed"
        | "freeFlowSpeed"
        | "congestionLevel"
        | "travelTime"
        | "networkLength"
    )[],
): void
Clears any active tile filter for one or more metrics.
Parameters
- Optionalmetrics: ("speed" | "freeFlowSpeed" | "congestionLevel" | "travelTime" | "networkLength")[]
  Optional list of metrics to clear. When omitted, clears filters for all metrics.
Returns void

filter

filter(
    filter?: AreaAnalyticsMetricFilter,
    metrics?: (
        | "speed"
        | "freeFlowSpeed"
        | "congestionLevel"
        | "travelTime"
        | "networkLength"
    )[],
): void
Filters visible tiles by value range for one or more metrics.
Parameters
- Optionalfilter: AreaAnalyticsMetricFilter
  Filter config. Pass undefined to clear.
- Optionalmetrics: ("speed" | "freeFlowSpeed" | "congestionLevel" | "travelTime" | "networkLength")[]
  Optional list of metrics to target. When omitted, the filter is applied to all metrics.
Returns void
Example
```
// Filter all metrics
module.filter({ min: 20, max: 80 });

// Filter only a specific metric
module.filter({ min: 50 }, ['congestionLevel']);

// Clear filter for all metrics
module.filter(undefined);
```

getConfig

getConfig(): NonNullable<TrafficAreaAnalyticsConfig> | undefined
Retrieves a copy of the current module configuration.

This method returns a shallow copy of the configuration object that is currently applied to the module. If no configuration has been applied, it returns undefined.

Returns NonNullable<TrafficAreaAnalyticsConfig> | undefined
A shallow copy of the current configuration object, or undefined if no configuration is currently applied. The returned object is a copy to prevent unintended modifications to the internal state.
Remarks
The returned configuration object is a shallow copy, which means that while the top-level properties are copied, any nested objects or arrays are still referenced from the original configuration. This is sufficient for most use cases but should be kept in mind when dealing with complex configurations.
Example
```
// Apply a configuration
myModule.applyConfig({ visible: true, opacity: 0.8 });

// Later, retrieve the current configuration
const currentConfig = myModule.getConfig();
console.log(currentConfig); // { visible: true, opacity: 0.8 }

// When no config is applied
myModule.resetConfig();
console.log(myModule.getConfig()); // undefined
```
See
- applyConfig to modify the configuration
- resetConfig to clear the configuration
Inherited from AbstractMapModule.getConfig

getShown

getShown(): {
    heatmap: FeatureCollection<Point, AreaAnalyticsDisplayProperties>;
    hexgrid: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
    square: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
}
Returns the currently displayed data for all visualisation modes.

Returns {
    heatmap: FeatureCollection<Point, AreaAnalyticsDisplayProperties>;
    hexgrid: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
    square: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
}

isVisible

isVisible(): boolean
Whether any area analytics (data) layer is currently visible.

Returns boolean

moveBeforeLayer

moveBeforeLayer(layerConfig: AreaAnalyticsBeforeLayerConfig): void
Repositions analytics layers independently by layer type.

Only the properties present in layerConfig are repositioned; omitted layer types are left in place.
Parameters
- layerConfig: AreaAnalyticsBeforeLayerConfig
  Per-layer-type positioning config. Each value is 'top' or a MapStyleLayerID.
Returns void

resetConfig

resetConfig(): void
Resets the configuration of this module to its default values.

This is a convenience method that clears any previously applied configuration and restores the module to its initial state. This is equivalent to calling applyConfig(undefined).

Returns void
Remarks
After calling this method, the module will behave as if no configuration was ever applied. Any custom settings, styling, or behavior modifications will be removed and replaced with default values.
Example
```
// Apply some configuration
myModule.applyConfig({ visible: true, opacity: 0.5 });

// Later, reset to defaults
myModule.resetConfig();
```
See
- applyConfig to apply a new configuration
- getConfig to retrieve the current configuration before resetting
Inherited from AbstractMapModule.resetConfig

setColor

setColor(
    color:
        | AreaAnalyticsColorTheme
        | AreaAnalyticsColorStopsConfig
        | undefined,
    metrics?: (
        | "speed"
        | "freeFlowSpeed"
        | "congestionLevel"
        | "travelTime"
        | "networkLength"
    )[],
): void
Sets the color for one or more metrics.

Pass a preset theme name or a custom color-stops configuration. Pass undefined to clear the color override for the targeted metrics.
Parameters
- color: AreaAnalyticsColorTheme | AreaAnalyticsColorStopsConfig | undefined
  A preset theme, an AreaAnalyticsColorStopsConfig, or undefined to clear.
- Optionalmetrics: ("speed" | "freeFlowSpeed" | "congestionLevel" | "travelTime" | "networkLength")[]
  Optional list of metrics to target. When omitted, the color is applied to all metrics.
Returns void
Example
```
// Apply a theme to all metrics
module.setColor('heat');

// Apply a theme to specific metrics only
module.setColor('heat', ['speed', 'freeFlowSpeed']);

// Apply custom stops to a single metric
module.setColor(
  { valueType: 'raw', stops: [{ value: 0, color: '#2dc653' }, { value: 100, color: '#e03030' }] },
  ['congestionLevel'],
);

// Clear color override for all metrics
module.setColor(undefined);

// Clear color override for a specific metric
module.setColor(undefined, ['speed']);
```

setHeight

setHeight(
    heightConfig: AreaAnalyticsHeightConfig,
    metrics?: (
        | "speed"
        | "freeFlowSpeed"
        | "congestionLevel"
        | "travelTime"
        | "networkLength"
    )[],
): void
Configures extrusion height behaviour for one or more metrics.
Parameters
- heightConfig: AreaAnalyticsHeightConfig
  Height configuration.
- Optionalmetrics: ("speed" | "freeFlowSpeed" | "congestionLevel" | "travelTime" | "networkLength")[]
  Optional list of metrics to target. When omitted, the height config is applied to all metrics.
Returns void
Example
```
// Apply to all metrics
module.setHeight({ maxHeightMeters: 100, minHeightMeters: 5 });

// Apply only to specific metrics
module.setHeight({ scaleMode: 'currentRange', maxHeightMeters: 500 }, ['speed', 'freeFlowSpeed']);
```

setMetric

setMetric(
    metric:
        | "speed"
        | "freeFlowSpeed"
        | "congestionLevel"
        | "travelTime"
        | "networkLength",
): void
Changes the active metric that drives colour and height.

Updates activeMetric in the config to the given metric key.
Parameters
- metric: "speed" | "freeFlowSpeed" | "congestionLevel" | "travelTime" | "networkLength"
  One of 'congestionLevel', 'speed', 'travelTime', 'freeFlowSpeed', or 'networkLength'.
Returns void

setMode

setMode(mode: AreaAnalyticsDisplayMode): void
Switches the visualisation mode.
Parameters
- mode: AreaAnalyticsDisplayMode
  One of 'heatmap', 'hexgrid-3d', 'hexgrid-2d', 'square-3d', 'square-2d'.
Returns void

setVisible

setVisible(visible: boolean): void
Shows or hides all area analytics layers.
Parameters
- visible: boolean
Returns void

show

show(analytics: TrafficAreaAnalytics): Promise<void>
Displays area analytics data on the map.

Accepts the raw response from trafficAreaAnalytics(). Tile data is transformed internally to point features (heatmap), hexagonal polygons (hexgrid modes), and square polygons (square modes). The region boundary geometry is also displayed.
Parameters
- analytics: TrafficAreaAnalytics
  The raw TrafficAreaAnalytics service response.
Returns Promise<void>
Example
```
const analytics = await trafficAreaAnalytics({ ... });
await module.show(analytics);
```

`Protected`waitUntilModuleReady

waitUntilModuleReady(): Promise<void>
Returns Promise<void>
Inherited from AbstractMapModule.waitUntilModuleReady

`Static`get

get(
tomtomMap: TomTomMap,
config?: TrafficAreaAnalyticsConfig,
): Promise<TrafficAreaAnalyticsModule>
Creates and initialises a new Traffic Area Analytics module.

All configuration properties are optional. When config is omitted (or only partially supplied), built-in defaults are applied for every missing field. After get() resolves, TrafficAreaAnalyticsModule.getConfig always returns a fully-populated configuration — there is no need to reference any default values yourself.
Parameters
- tomtomMap: TomTomMap
  The TomTomMap instance.
- Optionalconfig: TrafficAreaAnalyticsConfig
  Optional initial configuration. Omit to use all defaults.
Returns Promise<TrafficAreaAnalyticsModule>
A promise that resolves with the initialised module.
Example
```
// No config needed — defaults are applied automatically.
const module = await TrafficAreaAnalyticsModule.get(map);
await module.show(analytics);

// Or override specific properties while keeping everything else at default:
const module = await TrafficAreaAnalyticsModule.get(map, {
  displayMode: 'heatmap',
  metricConfig: {
    congestionLevel: { color: 'heat' },
  },
});
```

Class TrafficAreaAnalyticsModule

Remarks

Hierarchy (View Summary)

Index

Accessors

Methods

Accessors

events

Returns CombinedEvents< AreaAnalyticsTileFeature, TrafficAreaAnalyticsConfig, TrafficAreaAnalytics,>

Example

sourceAndLayerIDs

Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

Remarks

Example

Methods

applyConfig

Parameters

Returns void

Remarks

Example

See

clear

Returns Promise<void>

clearFilter

Parameters

Returns void

filter

Parameters

Returns void

Example

getConfig

Returns NonNullable<TrafficAreaAnalyticsConfig> | undefined

Remarks

Example

See

getShown

Returns { heatmap: FeatureCollection<Point, AreaAnalyticsDisplayProperties>; hexgrid: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>; square: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;}

isVisible

Returns boolean

moveBeforeLayer

Parameters

Returns void

resetConfig

Returns void

Remarks

Example

See

setColor

Parameters

Returns void

Example

setHeight

Parameters

Returns void

Example

setMetric

Parameters

Returns void

setMode

Parameters

Returns void

setVisible

Parameters

Returns void

show

Parameters

Returns Promise<void>

Example

ProtectedwaitUntilModuleReady

Returns Promise<void>

Staticget

Parameters

Returns Promise<TrafficAreaAnalyticsModule>

Example

Settings

On This Page

Returns CombinedEvents<
AreaAnalyticsTileFeature,
TrafficAreaAnalyticsConfig,
TrafficAreaAnalytics,
>

Returns {
heatmap: FeatureCollection<Point, AreaAnalyticsDisplayProperties>;
hexgrid: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
square: FeatureCollection<Polygon, AreaAnalyticsDisplayProperties>;
}

`Protected`waitUntilModuleReady

`Static`get