TomTom LogoDocs
Products
Resources
Pricing
Sign in
Maps SDK for JavaScript
Introduction
Guides
Examples
API Reference

Traffic

VERSION 0.46.1PUBLIC PREVIEW

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

ContextTypeDescription
Incident Details serviceTrafficIncident / TrafficIncidentDetailsParsed API response from the Incident Details service
Traffic Incidents map moduleTrafficIncidentsModuleFeatureVector-tile feature from the live incidents layer
RoutingTrafficSectionPropsRoute section affected by a traffic incident

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;
ValueMeaning
unknownSeverity cannot be determined
minorSmall delay (a few minutes)
moderateNoticeable delay (several minutes)
majorSignificant delay (10+ minutes)
indefiniteUnknown or extremely long delay (e.g. road closure)

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:

FieldTypeDescription
eventsTrafficIncidentEvent[]One or more event descriptions
fromstring?Start of the affected road stretch
tostring?End of the affected road stretch
lengthInMetersnumber?Length of the affected road section
roadNumbersstring[]?Highway designations (e.g. ['A10'])
timeValidityTrafficIncidentTimeValidityAlways present in the service response
tmcTrafficIncidentTMC?TMC location data

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