TomTom Maps SDK for JavaScript
This is the documentation of version 0.62.3. Go to the latest version, 1.0.0-rc.5.
TomTom Maps for JavaScript
    Preparing search index...

    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.

    Quick start:

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

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

    Hierarchy (View Summary)

    Index
    events sourceAndLayerIDs
    applyConfig cleanEventState cleanEventStates clear getConfig getEventStates getShown isVisible putEventState resetConfig setColorStops setFilters setHeight setPalette setVisible show updateConfig waitUntilModuleReady create
    • 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.

      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
      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');
      });

    • 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: TrafficAreaAnalyticsModuleConfig | undefined

        The configuration object to apply to the module. Pass undefined to reset the configuration to default values.

      Returns void

      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.

      The given configuration replaces the current one rather than being merged into it. To change one part of it, use updateConfig.

      // Apply a new configuration
      myModule.applyConfig({ visible: true, opacity: 0.8 });

      // Reset to default configuration
      myModule.applyConfig(undefined);
      • resetConfig for a convenience method to reset configuration
      • getConfig to retrieve the current configuration

    • Removes all area analytics data from the map.

      Returns Promise<void>

    • 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<TrafficAreaAnalyticsModuleConfig> | 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.

      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.

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

    • Returns the ids of the shown features that have an event state, by state.

      Returns EventStateIds

      The read side of putEventState and cleanEventStates: it reflects those and the states user interactions put. The ids are those getShown() and the event handlers hand back, so each can go straight back into putEventState.

      // Keep a list in sync with the selected feature
      const { click: [selectedID] = [] } = module.getEventStates();

      // Is this feature hovered?
      const hovered = module.getEventStates().hover?.includes(feature.id) ?? false;

    • Whether the module is set to be shown: its visible setting, true unless set. A shown module with nothing shown draws nothing; getShown() returns what is shown.

      Returns boolean

    • Puts an event state on one of the shown features, as a user interaction would.

      Parameters

      Returns void

      The state is what the module's own layers draw (place pins and entry points, route outlines, geometries, details-module incidents, area-analytics cells), what layers of yours read with ['get', 'eventState'], and what getEventStates returns. It lasts as long as the shown feature does: through setVisible, style and configuration changes, not through a new show, a clear or a setStyle with resetState.

      // Select a feature from a list, as a click would
      module.putEventState({ id: feature.id, state: 'click' });

      // Hover a second one without taking the hover off the first
      module.putEventState({ index: 2, state: 'hover', mode: 'add' });

    • 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

      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.

      // Apply some configuration
      myModule.applyConfig({ visible: true, opacity: 0.5 });

      // Later, reset to defaults
      myModule.resetConfig();
      • applyConfig to apply a new configuration
      • getConfig to retrieve the current configuration before resetting

    • Sets explicit colour stops on one or more metrics, which win over their palette.

      Parameters

      • colorStops: AreaAnalyticsColorStopsConfig | undefined

        The stops, or undefined to clear them so the palette paints again.

      • Optionalmetrics: ("speed" | "freeFlowSpeed" | "congestionLevel" | "travelTime" | "networkLength")[]

        The metrics to set them on. When omitted, all metrics.

      Returns void

      module.setColorStops(
        { valueType: 'raw', stops: [{ value: 0, color: '#2dc653' }, { value: 100, color: '#e03030' }] },
        ['congestionLevel'],
      );
      module.setColorStops(undefined);                     // every metric back to its palette

    • Filters visible tiles by value range for one or more metrics.

      Parameters

      • filters: AreaAnalyticsMetricFilter | undefined
      • Optionalmetrics: ("speed" | "freeFlowSpeed" | "congestionLevel" | "travelTime" | "networkLength")[]

        Optional list of metrics to target. When omitted, the filter is applied to all metrics.

      Returns void

      // Filter all metrics
      module.setFilters({ min: 20, max: 80 });

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

      // Clear the filters of every metric
      module.setFilters(undefined);

    • 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

      // Apply to all metrics
      module.setHeight({ maxHeightMeters: 100, minHeightMeters: 5 });

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

    • Sets the palette of one or more metrics, as AreaAnalyticsMetricConfig.palette describes.

      A metric whose colorStops are set keeps painting with them; clear those with setColorStops(undefined) for the palette to show.

      Parameters

      • palette: "trafficLight" | "heat" | "monochrome" | "viridis" | "plasma" | undefined

        The palette, or undefined to clear it back to trafficLight.

      • Optionalmetrics: ("speed" | "freeFlowSpeed" | "congestionLevel" | "travelTime" | "networkLength")[]

        The metrics to set it on. When omitted, all metrics.

      Returns void

      module.setPalette('heat');                           // every metric
      module.setPalette('viridis', ['speed', 'freeFlowSpeed']);
      module.setPalette(undefined, ['speed']);             // back to 'trafficLight'

    • Shows or hides everything the module draws.

      Parameters

      • visible: boolean

      Returns void

      Stored as visible in the configuration. Showing and clearing data never change it: a hidden module keeps its data, through style changes too, and draws it again on setVisible(true).

      Showing leaves hidden what the configuration turns off: a route section type that is off, the layers a place marker type does not use.

      module.setVisible(false);
      await module.show(data); // stays hidden
      module.setVisible(true);

    • 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

      Returns Promise<void>

      const analytics = await trafficAreaAnalytics({ ... });
      await module.show(analytics);

    • Changes part of the configuration and keeps the rest.

      The given properties are laid over the current configuration — one level deep, so a nested object you pass replaces the nested object that was there — and the result is applied with applyConfig. This is the same on every module, whatever its applyConfig does with a whole configuration.

      Parameters

      • partial: Partial<NonNullable<CFG>>

        The properties to change.

      Returns void

      routing.applyConfig({ displayUnits: 'imperial', color: '#0a3653' });
      routing.updateConfig({ color: '#c2185b' }); // displayUnits stays imperial

      applyConfig to apply a whole configuration

    • 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 create() resolves, TrafficAreaAnalyticsModule.getConfig always returns a fully-populated configuration — there is no need to reference any default values yourself.

      TrafficAreaAnalyticsModule owns the sources, layers and images it adds, all suffixed per instance. Every call therefore returns a new, independent instance, and stacking several of them on one map is a supported thing to do.

      trafficAreaAnalyticsKnobCatalogue lists the plain-valued settings of config as data.

      Parameters

      Returns Promise<TrafficAreaAnalyticsModule>

      A promise that resolves with the initialised module.

      // No config needed — defaults are applied automatically.
      const module = await TrafficAreaAnalyticsModule.create(map);
      await module.show(analytics);

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

    Settings
    Member Visibility

    On This Page
    Accessors
    Methods