Traffic

The @tomtom-org/maps-sdk/core package exports a set of shared traffic types used consistently across the SDK — in the Incident Details service, the Traffic Incidents map module, and route sections. Using the same types across all three ensures that incident data is interoperable regardless of how it was obtained.

Where Traffic Types Are Used

Shared Types

TrafficIncidentCategory

The human-readable category string used across the Incident Details service and the Traffic Incidents map module:

import type { TrafficIncidentCategory } from '@tomtom-org/maps-sdk/core';

// 'accident' | 'animals-on-road' | 'broken-down-vehicle' | 'danger' |
// 'flooding' | 'fog' | 'frost' | 'jam' | 'lane-closed' | 'narrow-lanes' |
// 'other' | 'rain' | 'road-closed' | 'roadworks' | 'wind'
const category: TrafficIncidentCategory = incident.properties.category;

The trafficIncidentCategories constant exports the full list as an array, useful for building UI filters or validation:

import { trafficIncidentCategories } from '@tomtom-org/maps-sdk/core';

// ['accident', 'animals-on-road', 'broken-down-vehicle', ...]
console.log(trafficIncidentCategories);

DelayMagnitude

Describes how severe a traffic delay is. Used by both the Incident Details service (TrafficIncidentProperties.magnitudeOfDelay) and routing sections (TrafficSectionProps.magnitudeOfDelay):

import type { DelayMagnitude } from '@tomtom-org/maps-sdk/core';

// 'unknown' | 'minor' | 'moderate' | 'major' | 'indefinite'
const severity: DelayMagnitude = incident.properties.magnitudeOfDelay;

TrafficIncidentTimeValidity

Whether an incident is currently active or anticipated in the future. Used by both the Incident Details service and the Traffic Incidents map module:

import type { TrafficIncidentTimeValidity } from '@tomtom-org/maps-sdk/core';

// 'present' | 'future'
const validity: TrafficIncidentTimeValidity = incident.properties.timeValidity;

Incident Types

TrafficIncidentBaseProperties

The nine properties shared between the Incident Details service response and the Traffic Incidents map module vector-tile feature. This is the intersection between the two data sources:

import type { TrafficIncidentBaseProperties } from '@tomtom-org/maps-sdk/core';

type TrafficIncidentBaseProperties = {
    id: string;
    category: TrafficIncidentCategory;
    magnitudeOfDelay: DelayMagnitude;
    delayInSeconds?: number;
    startTime?: Date;
    endTime?: Date;
    probabilityOfOccurrence?: TrafficIncidentProbability;
    numberOfReports?: number;
    lastReportTime?: Date;
};

TrafficIncidentProperties

Extends TrafficIncidentBaseProperties with fields available only in the Incident Details API response (not in map vector tiles):

import type { TrafficIncidentProperties } from '@tomtom-org/maps-sdk/core';

Additional fields over the base:

TrafficIncident and TrafficIncidentDetails

import type { TrafficIncident, TrafficIncidentDetails } from '@tomtom-org/maps-sdk/core';

// TrafficIncident — a single GeoJSON Feature<Point | LineString, TrafficIncidentProperties>
// TrafficIncidentDetails — a GeoJSON FeatureCollection of TrafficIncident features

TrafficIncidentDetails is the return type of the trafficIncidentDetails service function.

Routing Traffic Types

TrafficSectionProps

Route sections flagged by the routing engine as traffic-affected share TrafficIncidentCategory and DelayMagnitude with the incident types above:

import type { TrafficSectionProps } from '@tomtom-org/maps-sdk/core';

const trafficSections = route.properties.sections?.traffic ?? [];

for (const section of trafficSections) {
    // categories uses TrafficIncidentCategory — same values as incident.properties.category
    console.log(section.categories);        // e.g. ['jam']
    // magnitudeOfDelay uses DelayMagnitude — same values as incident.properties.magnitudeOfDelay
    console.log(section.magnitudeOfDelay);  // e.g. 'moderate'
    console.log(section.delayInSeconds);    // e.g. 420
}

The tec field on TrafficSectionProps contains TPEG2-TEC standardized codes. These are separate from the tmc field on incident details and relate to international traffic message classification.

Related

• Incident Details service — Fetch real-time incident data
• Traffic Incidents map module — Display the live incident layer
• Routing with Traffic — Plan routes that account for traffic