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

    Class TrafficFlowModule

    The module that shows and configures real-time traffic flow on the map.

    It controls the vector tile traffic flow layers, which colour road segments by current traffic speed.

    The module owns whether the style's traffic-flow layers are shown, for which roads, and how they look, through each flow level's colour (colors) and the line width (widthFactor). See Who owns what.

    Features:

    • Toggle traffic flow visibility on/off
    • Filter by road categories and types
    • Colour-coded speed visualization (green = free flow, red = congestion)
    • Real-time traffic data from vector tiles
    • Filter road closures

    The colours:

    • Green: Free-flowing traffic
    • Yellow/Orange: Slow traffic
    • Red: Heavy congestion
    • Dark gray: Road closures

    Basic usage:

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

    // Get module (auto-add to style if needed)
    const trafficFlow = await TrafficFlowModule.get(map, {
      visible: true
    });

    // Toggle visibility
    trafficFlow.setVisible(false);
    trafficFlow.setVisible(true);

    Filter by road type:

    // Show only highway traffic
    trafficFlow.updateConfig({
      filters: { roadCategories: { show: 'only', values: ['motorway', 'trunk'] } },
    });

    // Hide local streets
    trafficFlow.updateConfig({
      filters: { roadCategories: { show: 'all-except', values: ['street'] } },
    });

    // Show only road closures
    trafficFlow.updateConfig({ filters: { roadClosures: 'only' } });

    // Show all traffic again
    trafficFlow.updateConfig({ filters: undefined });

    Restyle the flow:

    trafficFlow.updateConfig({ colors: { slow: '#ffb000', stationary: '#b00020' }, widthFactor: 1.5 });

    Hierarchy (View Summary)

    Index
    events sourceAndLayerIDs
    applyConfig getConfig getRenderedFeatures isVisible resetConfig setVisible updateConfig waitUntilModuleReady get
    • get sourceAndLayerIDs(): Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      The MapLibre source and layer IDs of all sources this module creates and manages.

      Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      A record mapping each source name to its MapLibre source ID and an array of the IDs of that source's layers.

      Use these IDs 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.

      The module updates its behaviour and appearance to match. It stores the configuration and reapplies it automatically when the map style changes.

      Parameters

      • config: TrafficFlowModuleConfig | undefined

        The configuration to apply. Pass undefined to reset it to the default values.

      Returns void

      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, color: '#E63312' });

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

    • Returns a shallow copy of the current module configuration, or undefined if none is applied.

      Returns NonNullable<TrafficFlowModuleConfig> | undefined

      A shallow copy of the current configuration, or undefined. It is a copy so that you can't modify the internal state by accident.

      Only the top-level properties are copied. Nested objects and arrays still reference the original configuration. This is enough for most use cases, but keep it in mind with complex configurations.

      // Apply a configuration
      myModule.applyConfig({ visible: true, color: '#E63312' });

      // Later, retrieve the current configuration
      const currentConfig = myModule.getConfig();
      console.log(currentConfig); // { visible: true, color: '#E63312' }

      // When no config is applied
      myModule.resetConfig();
      console.log(myModule.getConfig()); // undefined

    • Returns the features the map renders in the viewport, from its vector tiles.

      Returns { trafficFlow: TrafficFlowModuleFeature[] }

      An object containing visible traffic flow features.

      This is the only way to read live flow values, because Orbis traffic flow is vector tiles, with no service for a road, a point or an area. Results cover the current viewport and zoom, and a segment crossing a tile boundary appears once per tile. See TrafficFlowModuleFeature for what each carries.

      const rendered = trafficFlow.getRenderedFeatures();
      console.log(`Visible flow segments: ${rendered.trafficFlow.length}`);
      rendered.trafficFlow.forEach(segment => {
        console.log('Road segment:', segment.properties);
      });

      Analyze congestion in viewport:

      const rendered = trafficFlow.getRenderedFeatures();
      const congested = rendered.trafficFlow.filter(
        segment => segment.properties.relativeSpeed < 0.5
      );
      console.log(`Congested segments: ${congested.length}`);

    • Whether traffic flow is set to be shown.

      Returns boolean

      The visible setting, or false if nothing has set it, as traffic is hidden until shown.

    • Resets this module's configuration to its default values.

      It clears any applied configuration and restores the module to its initial state, the same as calling applyConfig(undefined).

      Returns void

      The module then behaves as if no configuration was ever applied. Any custom settings, styling or behaviour changes are replaced with default values.

      // Apply some configuration
      myModule.applyConfig({ visible: true, color: '#E63312' });

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

    • Sets the visibility of traffic flow layers.

      Parameters

      • visible: boolean

        true to show traffic flow, false to hide it.

      Returns void

      trafficFlow.setVisible(true);  // Show traffic
      trafficFlow.setVisible(false); // Hide traffic

    • 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 one that was there. The result is applied with applyConfig. This works 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: { distance: { type: 'imperial_us' } }, color: '#0a3653' });
      routing.updateConfig({ color: '#c2185b' }); // displayUnits stays imperial

      applyConfig to apply a whole configuration

    • Retrieves a TrafficFlowModule instance for the given map.

      Parameters

      Returns Promise<TrafficFlowModule>

      A promise that resolves to the initialized TrafficFlowModule.

      The configuration takes:

      • visible - The initial visibility.
      • filters - Road category and type filters.

      trafficFlowKnobCatalogue lists the plain-valued settings as data.

      If the style lacks traffic flow, get() reloads it with the trafficFlow part included.

      Default initialization:

      const trafficFlowModule = await TrafficFlowModule.get(map);

      Visible, with filters:

      const trafficFlowModule = await TrafficFlowModule.get(map, {
        visible: true,
        filters: {
          any: [{
            roadCategories: {
              show: 'only',
              values: ['motorway', 'trunk', 'primary']
            }
          }]
        }
      });

    Settings
    Member Visibility

    On This Page
    Accessors
    Methods