Incident details

trafficIncidentDetails returns the current and planned traffic incidents of an area, or of a list of known incident IDs, as a GeoJSON FeatureCollection (TrafficIncidentDetails). Each incident is a Point or LineString feature, ready to process server-side or to draw with the Traffic Incident Details Module.

Core concepts

An incident (TrafficIncident) carries:

• Category (category): what happened — accident, jam, roadworks, road-closed, … (TrafficIncidentCategory).
• Delay magnitude (magnitudeOfDelay): unknown, minor, moderate, major, or indefinite for road closures (DelayMagnitude).
• Geometry: a Point for a localised incident, a LineString for one spanning a stretch of road.
• Time validity (timeValidity): present, active now, or future, planned.
• Events (events): one or more descriptions of what is happening there.

Basic usage

A call takes exactly one of bbox, polygon or ids.

Query by bounding box

bbox takes a [minLon, minLat, maxLon, maxLat] tuple, or any GeoJSON object, whose bounding box the SDK computes:

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { geocodeOne, trafficIncidentDetails } from '@tomtom-org/maps-sdk/services';

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });

const place = await geocodeOne('Amsterdam');
const result = await trafficIncidentDetails({ bbox: place });

result.features.forEach((incident) => {
    const { category, magnitudeOfDelay, from, to } = incident.properties;
    console.log(`${category} — ${magnitudeOfDelay} delay: ${from} → ${to}`);
});

const inBox = await trafficIncidentDetails({ bbox: [4.728, 52.278, 5.08, 52.479] });

The bounding box covers at most 10,000 km².

Query by polygon

A bounding box over-covers any place that is not a rectangle. Pass the place's boundary as polygon instead, such as the one geometryData returns:

import { geocodeOne, geometryData, trafficIncidentDetails } from '@tomtom-org/maps-sdk/services';

const place = await geocodeOne('Amsterdam');
const boundary = await geometryData({ geometries: [place] });
const result = await trafficIncidentDetails({ polygon: boundary });

• polygon takes a Polygon or MultiPolygon, a Feature wrapping one, or a FeatureCollection of them.
• The API only takes a bounding box, so the request covers the polygon's, and the response keeps the incidents intersecting the polygon. A LineString incident crossing the boundary is kept.
• The 10,000 km² limit applies to the polygon's bounding box.

Query by incident IDs

const result = await trafficIncidentDetails({
    ids: ['incident-id-1', 'incident-id-2', 'incident-id-3'],
});

• Up to 100 IDs; more than 5 are sent as a POST, which the SDK picks.
• A live incident tile's id from the Traffic Incidents Module, and a route traffic section's eventId (TrafficSectionProps), look the full record up here.

Filtering results

By category

categoryFilter keeps the given categories:

const result = await trafficIncidentDetails({
    bbox: [4.728, 52.278, 5.08, 52.479],
    categoryFilter: ['accident', 'road-closed'],
});

It takes the trafficIncidentRequestCategories (TrafficIncidentRequestCategory). The two other values of fullTrafficIncidentCategories, 'animals-on-road' and 'narrow-lanes', occur only on the traffic vector tiles, so they are neither accepted nor returned here.

By time validity

Only 'present' incidents come back by default. Add 'future' for planned works and scheduled events:

const result = await trafficIncidentDetails({
    bbox: [4.728, 52.278, 5.08, 52.479],
    timeValidityFilter: ['present', 'future'],
});

By severity

The request takes no magnitude; filter the response on magnitudeOfDelay:

const severeIncidents = result.features.filter(({ properties }) =>
    properties.magnitudeOfDelay === 'major' || properties.magnitudeOfDelay === 'indefinite',
);

Working with incident data

Reading incident properties

const incident = result.features[0];

incident.geometry.type; // 'Point' | 'LineString'

const {
    id,
    category,
    magnitudeOfDelay,
    events,                  // [{ description, code, category }]
    from,
    to,
    lengthInMeters,
    delayInSeconds,
    roadNumbers,             // e.g. ['A10']
    timeValidity,            // 'present' | 'future'
    probabilityOfOccurrence, // 'certain' | 'probable' | 'risk_of' | 'improbable'
    startTime,               // Date | undefined
    endTime,                 // Date | undefined
    numberOfReports,
    lastReportTime,          // Date | undefined
} = incident.properties;

TrafficIncidentProperties lists which are always present.

Displaying on a map

The Traffic Incident Details Module draws the response in the style's incident look, and highlights a subset with setFocus:

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

const incidentDetailsModule = await TrafficIncidentDetailsModule.create(map);
await incidentDetailsModule.show(result);

Error handling

A failed call rejects with an SDKServiceError, carrying the HTTP status and the service; an invalid request, such as one with both bbox and ids, rejects before it is sent (Error handling).

API reference

• trafficIncidentDetails
• TrafficIncidentDetailsParams – Request parameters
• TrafficIncidentDetails – Response type

Related guides and examples

Related examples

• Traffic incident details NodeJS - A city's incidents, printed
• Traffic incident details - A city's incidents clipped to its boundary, on a map
• Traffic incidents - The live incident tiles, with no request

Related guides

• Core traffic types - The incident types this service returns
• Traffic incident details module - Draw the response on a map
• Routing parameters - Routes whose travel times account for live traffic