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 - What happened, such as accident, jam, roadworks or road-closed (TrafficIncidentCategory).
• magnitudeOfDelay - unknown, minor, moderate, major, or indefinite for road closures (DelayMagnitude).
• Geometry - A Point for a localised incident, or a LineString for one spanning a stretch of road.
• timeValidity - present (active now) or future (planned).
• 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 covers more than any place that isn't 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 SDK requests the polygon's bounding box and keeps only incidents that intersect the polygon, including LineString incidents that cross the boundary.
• 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'],
});

• Pass up to 100 IDs. For more than 5, the SDK sends a POST.
• To look up the full record, pass a live incident tile's id from the Traffic Incidents Module, or a route traffic section's eventId (TrafficSectionProps).

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 this service neither accepts nor returns them.

By time validity

By default, only 'present' incidents come back. 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 has no magnitude filter, so 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. Its setFocus highlights a subset:

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 SDKError whose code says what went wrong. An API error rejects with an SDKServiceError, which also carries the HTTP status. 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