Maps SDK for Web

tt.services.incidentDetails

New version incidentDetailsV5

The new incidentDetailsV5 method was introduced. We highly recommend using the new V5 version.

Old version

The incidentDetails service has been deprecated.
This service will be withdrawn following a 12 months deprecation period.
The planned withdrawal period is April of 2022.
Following withdrawal, requests to this service may receive an HTTP 404 error in response.

Provides current traffic incidents in a given region, on a given zoom level with a given style using the TomTom Traffic API - Traffic Incidents Details

The current road situation is updated every minute. Please use the IncidentViewport service in conjunction with your request to get traffic incidents aligned with other services.

Parameters need to be passed to the constructor.

Response

This service extends API response by providing toGeoJson() method, which converts incidents data into FeatureCollection with Point geometry.

Each point feature represents poi from the original response. Properties of poi are mapped into feature properties

We convert original properties from the API response to more readable format:

cbl - clusterBounds
ic - incidentCategory
ty - incidentSeverity
cs - clusterSize
d - description
c - incidentCause
f - from
t - to
r - roadNumber
dl - delaySeconds
l - lengthMeters
v - vectorGeometry
ed - endDate

Please refer directly to Traffic API - Traffic Incidents Details too see exactly what they mean.

Additionally, the response is extended with getTrackingId() method, which returns the Tracking-ID associated with the request.

To read more about services responses take a look at Difference between API responses and this library's responses section.

Constructor

tt.services.incidentDetails([options], [additionalOptions])

Example

function callbackFn(response) {
  console.log(response.toGeoJson());
}
tt.services.incidentDetails({
  key: '<Your API key>',
  boundingBox: '0,0,1,1',
  style: 's1',
  zoomLevel: 12
}).then(callbackFn);

Parameters

Name	Description
options Object default:None
additionalOptions Object default:None	Additional options to be passed to the service.
additionalOptions.abortSignal Object default:None	Signal created with abortController. Use AbortController to cancel requests in progress. Example `var abortController = new AbortController(); var options = {}; tt.services.calculateRoute(options, { abortSignal: abortController.signal }) .then(function(response) { console.log(response) }); .catch(function(error) { if (abortController.signal.aborted === true) { console.log('Request aborted.'); } }); abortController.abort();`
options.boundingBox Maps.LngLatBounds \| Number[] \| Object[] \| String default:None	Bounding box area in one of the supported formats. The bounding box is a limited area within the search results. If it is omitted then the whole world will be taken into consideration. In case the area specified exceeds the world boundaries, the following actions will be taken depending on which side was exceeded: Latitudes: the exceeded values will be replaced with their maximun. Longitudes: The service will split the area into two (or more) valid bounding boxes, will execute a search request for each one, and then merge the responses into a single result. This option is able to convert a number of popular formats into the bounding box. The supported formats are listed below: Maps.LngLatBounds class instance `{minLon: 0, minLat: 0, maxLon: 1, maxLat: 1}` A plain object with the keys minLon, minLat, maxLon, maxLat. `[0, 0, 1, 1]` An array of numbers describing the bounding box following the order: minLon, minLat, maxLon, maxLat. `[[0, 0], [1, 1]]` A two-dimensional array with two indexes [southWest, northEast], each one with longitude and latitude values. `"0,0,1,1"` A comma-separated string with numbers in the order: minLon, minLat, maxLon, maxLat. `[{lon: 0, lat: 0},{lon: 1, lat: 1}]` A one-dimensional array with two objects in the order: southWest, northEast, and each object with a `lat` and `lon` key. `[{lng: 0, lat: 0},{lng: 1, lat: 1}]` A one-dimensional array with two objects in the order: southWest, northEast and each object with a `lat` and `lon` key. `[Maps.LngLat, Maps.LngLat]` A one-dimensional array with two Maps.LngLat instances in the order: southWest and northEast.
options.expandCluster Boolean default:false	Determines if the service should include details of incidents that are clustered. Tells the service to separately list all traffic incidents in a cluster. When is enabled the clusters in the response will be represented as geometry collections, and the cluster coordinates will appear as clusterCoordinates parameters. Enabling this feature is useful when the user wants to obtain details of the incidents that are being clustered, or wants to perform a client-side clustering. Note that when this is set to false, the toGeoJson() method available in the resolved response will return only unclustered POIs, but no clusters.
options.geometries String default:None	The type of vector geometry added to incidents. If passed, additional field `poi.v` is added to the response and `properties.vectorGeometry` is added to the return value of toGeoJson() method. Two values are allowed: `original` places incidents precisely on the road. `shifted` moves the incident slightly (depending on the zoom level) to indicate specific road lanes. Returned vector geometry is encoded using Encoded Polyline Algorithm Format.
options.key Required String default:None	A valid API Key for the requested service. Key is required to make use of the given service. It can be issued in the Developer Portal.
options.language String default:null	Language code that decides in which language the results should be returned. The ISO 639-1 code for the output language. Affects the `incidentCause` and `description` fields in the response. When an invalid language code is provided the response is returned in English. When an incident cause or description does not have a translation, an English description is returned.
options.originalPosition Boolean default:false	Determines if the service should include the original incidents' position. Return the original position of the incident (`originalPosition` attribute) as well as the one shifted to the beginning of the traffic tube.
options.preserveCluster Boolean default:false	Determines if clustered incidents data should be available in the cluster feature. If this is set to true, the toGeoJson() method available in the resolved response will return features with an additional `properties.features` field containing clustered features. Note that this option only works in conjunction with `expandCluster` set to `true`.
options.protocol "http" \| "https" default:"https"	The protocol type to be used in the calls. Represents the type of protocol used to perform a service call.
options.style Required String default:None	Style name, needs to be one of 's1', 's2', 's3', 'night'. This needs to match the style of your raster traffic tiles to match traffic tubes with traffic icons. The style that will be used to render the traffic tile in the Maps API. This will have an effect on the coordinates of traffic incidents in the reply.
options.trackingId String default:uuid	Sets value of "Tracking-ID" header. Specifies an identifier for the request. If not set by the user, UUID is generated for each call. It can be used to trace a call. The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'. An example of the format that matches this regular expression is UUID: (e.g. 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1). For details check RFC 4122. If specified, it is replicated in the Tracking-ID Response header. It is only meant to be used for support and does not involve tracking of you or your users in any form.
options.trafficModelID Number default:None	A valid, not older than two minutes, traffic model ID. Number referencing the traffic model to use. This can be obtained from the IncidentViewport service. It is updated every minute, and is valid for two minutes before it times out. If a wrong Traffic Model ID is specified, the correct one will be returned by the interface. The default value of `-1` will always invoke the most recent traffic model. Nevertheless, it is good practice to use the value obtained from the service as this will guarantee an alignment with the raster traffic layer.
options.zoomLevel Required Number default:None	Zoom level from `0` to `22` The zoom level of a currently displayed map. It is needed as the style (visibility, clustering, etc...) depends on the current zoom level.