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

Traffic

VERSION 1.0.0-rc.7PUBLIC PREVIEW

@tomtom-org/maps-sdk/core exports the traffic types that the services, map modules and routing share, so an incident looks the same whichever API returns it.

Where traffic types are used

ContextTypeDescription
Incident Details serviceTrafficIncident / TrafficIncidentDetailsThe parsed incidents of a trafficIncidentDetails call
Traffic Incidents map moduleTrafficIncidentsModuleFeature (map)A live incident tile feature, extending TrafficIncidentBaseProperties
Route sectionsTrafficSectionPropsA stretch of route affected by a traffic incident
Traffic Area Analytics serviceTrafficAreaAnalytics, AreaAnalyticsMetricKeyA region’s historical traffic report and its metric names (areaAnalyticsMetricKeys)

Shared types

TrafficIncidentCategory

The kind of incident, used by the Incident Details service, the incident tiles and route sections:

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;
  • fullTrafficIncidentCategories lists every category, for UI filters or validation.
  • trafficIncidentRequestCategories (TrafficIncidentRequestCategory) lists the ones the Incident Details service’s categoryFilter accepts. It leaves out animals-on-road and narrow-lanes, which only the tiles carry.
import { fullTrafficIncidentCategories } from '@tomtom-org/maps-sdk/core';


// ['accident', 'broken-down-vehicle', 'danger', 'flooding', ..., 'animals-on-road', 'narrow-lanes']
console.log(fullTrafficIncidentCategories);

DelayMagnitude

The severity of a delay, in TrafficIncidentProperties.magnitudeOfDelay, TrafficSectionProps.magnitudeOfDelay and the values of the incidents module’s magnitudes filter:

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)

indexedMagnitudes lists every magnitude in the order above, which matches the Traffic API’s numeric magnitudeOfDelay codes. For example, index 2 is moderate. The SDK’s results already carry the names. Use it to build a magnitude filter or check whether all are selected:

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


const allSelected = selectedMagnitudes.length === indexedMagnitudes.length;

TrafficIncidentTimeValidity

Whether an incident is active now or planned, used by the Incident Details service and the incident tiles:

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


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

trafficIncidentTimeValidities lists both, present first, for a picker over the service’s timeValidityFilter or the incidents module’s timeValidity.

Incident types

TrafficIncidentBaseProperties

The nine properties the Incident Details response and the incident tile features share:

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; // 'certain' | 'probable' | 'risk_of' | 'improbable'
    numberOfReports?: number;
    lastReportTime?: Date;
};

TrafficIncidentProperties

TrafficIncidentBaseProperties plus what only the Incident Details response carries:

import type { TrafficIncidentProperties } from '@tomtom-org/maps-sdk/core';
FieldTypeDescription
eventsTrafficIncidentEvent[]One or more event descriptions, each with its description, code and category
fromstring?Start of the affected road stretch
tostring?End of the affected road stretch
lengthInMetersnumber?Length of the affected road section
roadNumbersstring[]?Road numbers (e.g. ['A10'])
timeValidityTrafficIncidentTimeValidityAlways present in the service response

TrafficIncident and TrafficIncidentDetails

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


// TrafficIncident — a GeoJSON Feature<Point | LineString, TrafficIncidentProperties>
// TrafficIncidentDetails — a GeoJSON FeatureCollection of them, what trafficIncidentDetails returns

Routing traffic types

TrafficSectionProps

A route’s traffic sections share TrafficIncidentCategory and DelayMagnitude with the incident types above:

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


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


for (const section of trafficSections) {
    console.log(section.categories);          // e.g. ['jam']
    console.log(section.magnitudeOfDelay);    // e.g. 'moderate'
    console.log(section.delayInSeconds);      // e.g. 420
    console.log(section.effectiveSpeedInKmh); // e.g. 18
}
  • eventId - The routing service’s id for the incident behind the section. To get the whole record, see Find the incident of a route traffic section.
  • tec - The section’s TPEG2-TEC codes, the international traffic message classification. A section without them has no tec, and its categories come from the incident’s icon category.