Incident Details
Service version: 4
Last edit: 2020.12.16
On this page
Purpose
This service provides information on traffic incidents whose bounding box intersects with a given bounding box, based on the given Traffic Model ID.
- The Traffic Model ID is available in order to have the synchronization of data between calls and different API's.
- The Traffic Model ID is a key value for determining the freshness of traffic incidents.
- It is updated every minute, and is valid for two minutes before it times out.
- It is also used in other Traffic Incident services.
- It can be obtained from the Viewport API.
Run this endpoint
You can easily run this and other endpoints.
- Go to the TomTom API Explorer page.
- Click an endpoint.
- Click Try it out.
- Enter/select all required parameter values and any optional parameter values.
- At the bottom of the form, click Execute.
- Review the Response.
Clustering
Clustering is the grouping of nearby or overlapping incidents.
- It is performed when a high density of incidents occurs, usually when the value of a zoom level is low.
- The clustering algorithm differs slightly between styles.
- Styles
s0
,s0-dark
,s1
,s2
use the same algorithm. - Style
night
does not group incidents into clusters.
- Styles
- When clustering is performed, the distances between the starting points of the incidents are taken into consideration.
- The bounding box coordinates of a cluster: bottom-left and top-right, are calculated based on the starting points of the incidents which make up the cluster.
- If the incident has shape/length, its end point might appear outside of the cluster.
Response creation
The Response contains incidents and clusters of incidents belonging to a given bounding box.
The following rules must be met to have a particular incident or cluster in the Response.
- If the incident does not have a shape/length, it must be located inside the bounding box.
- If the incident has a shape/length, its bounds must intersect with the requested bounding box.
- If at least one incident of a cluster meets these requirements, the whole cluster is qualified as belonging to the bounding box.
- If a cluster belongs to the requested bounding box, and the
expandCluster
option is used, all of the incidents from that particular cluster appear in the cluster expansion, not only those belonging to the requested bounding box.
- If a cluster belongs to the requested bounding box, and the
Request data
HTTPS method: GET
URL format
For ease of viewing and identification:
- Required constants and parameters are shown in bold text.
- Optional parameters are shown in plain text.
http(s)://baseURL/traffic/services/versionNumber/incidentDetails/style/boundingBox/zoom/trafficModelID/format?key=Your_Api_Key&language=language&projection=projection&geometries=geometries&expandCluster=expandCluster&originalPosition=originalPosition&jsonp=jsonp
Example
https://api.tomtom.com/traffic/services/4/incidentDetails/s3/6841263.950712,511972.674418,6886056.049288,582676.925582/11/1335294634919/xml?key=Your_Api_Key
curl command
curl-H'http(s)://baseURL/traffic/services/versionNumber/incidentDetails/style/boundingBox/zoom/trafficModelID/format?key=Your_Api_Key&language=language&projection=projection&geometries=geometries&expandCluster=expandCluster&originalPosition=originalPosition&jsonp=jsonp'
Request parameters
The following table describes all of the parameters that can be used in a request.
- Parameters and values are case-sensitive.
- Required parameters must be used or the call will fail.
- Optional parameters may be used.
- If an optional parameter is not specified, where applicable, the default value listed in the following table will be used.
Required parameters | |
---|---|
Parameter | Description |
baseURL string |
The base URL for calling the API. Value: api.tomtom.com |
versionNumber string |
The service version number. Value: The current value is 4 . |
style string |
The style used with Raster Incident Tiles and Vector Incident Tiles. This has an effect on the coordinates and encoded geometry of traffic incidents in the Response. Values:
|
boundingBox float |
The corners of the area to report on, expressed in the projection specified.
minY,minX,maxY,maxX , orminLat,minLon,maxLat,maxLon . |
zoom integer |
This is the zoom level. This will affect traffic incident coordinates and determine which incidents are included in clusters rather than reported separately. Value: 0..22 |
trafficModelID string |
The Traffic Model ID is the reference value for the state of traffic at a particular time.
-1 . |
format string |
The content type of the response structure. If the content type is jsonp, a callback method must be specified at the end of the service call. Value:
|
key string |
The authorization key for access to the API. Value: Your valid API Key. |
Optional parameters | |
Parameter | Description |
language string |
The ISO 639-1 code for the output language.
en Other values: ar, ca, cs, da, de, el, en, en-GB, en-US, es, et, fi, fr, he, hu, id, in*, it, iw*, lt, lv, nb, nl, no, pl, pt, ro, ru, sk, sv, th, tr, zh |
projection string |
The projection used to specify the coordinates in the Request and Response. Default value: EPSG900913 Other value: EPSG4326 |
geometries string |
The type of vector geometry added to incidents (returned in the <v> element of the Response).
<v> element.Values:
|
expandCluster boolean |
This separately lists all traffic incidents in a cluster. Default Value: false Other value: true |
originalPosition boolean |
This returns the original position of the incident (<op> ) as well as the one shifted to the beginning of the traffic tube (<p>).Default Value: false Other value: true |
jsonp string |
Specifies the callback method. Only used where the contentType is jsonp .Value: An asynchronous or synchronous function. |
Maximum bounding box
In an EPSG:900913 projection we use an extent of the world from -20037508.34 to 20037508.34 in each direction.
- On each zoom level the world is divided into 2zoom x 2zoom tiles.
- The maximum allowed size of the requested bounding box is a square of size 16 x 16 tiles.
- For zoom level 5 and greater, the width and height cannot exceed 40075016.68 / 2zoom - 4.
- An XSD response schema is available for download.
Query with XML cluster
https://api.tomtom.com/traffic/services/4/incidentDetails/s3/6841263.950712,511972.674418,6886056.049288,582676.925582/11/1335294634919/xml?key=Your_Api_Key
<tm id="1400168040337">
<poi>
<id>CLUSTER_581</id>
<p>
<x>294962.2</x>
<y>6535338.8</y>
</p>
<ic>13</ic>
<ty>1</ty>
<cbl>
<x>294223.5</x>
<y>6535005.4</y>
</cbl>
<ctr>
<x>295700.9</x>
<y>6535672.3</y>
</ctr>
<cs>2</cs>
<l>7430</l>
</poi>
<poi>
<id>CLUSTER_325</id>
<p>
<x>314807.6</x>
<y>6538765.0</y>
</p>
<ic>13</ic>
<ty>1</ty>
<cbl>
<x>313078.2</x>
<y>6538198.4</y>
</cbl>
<ctr>
<x>316536.9</x>
<y>6539331.6</y>
</ctr>
<cs>3</cs>
<l>2850</l>
</poi>
[...]
</tm>
Query with expanded cluster
https://api.tomtom.com/traffic/services/4/incidentDetails/s3/6841263.950712,511972.674418,6886056.049288,582676.925582/11/1335294634919/xml?key=Your_Api_Key&language=en&expandCluster=true
XML
<tm id="1400168682560">
<poi>
<id>TTR826194</id>
<p>
<x>581415.6</x>
<y>6535660.9</y>
</p>
<ic>6</ic>
<ty>3</ty>
<cs>0</cs>
<d>stationary traffic</d>
<f>Rue Joseph Wauters</f>
<t>Rue du Pont</t>
<l>1100</l>
<dl>558</dl>
<r>N90</r>
</poi>
<poi>
<id>CLUSTER_244</id>
<p>
<x>543483.8</x>
<y>6537828.8</y>
</p>
<ic>13</ic>
<ty>1</ty>
<cbl>
<x>543112.0</x>
<y>6537745.5</y>
</cbl>
<ctr>
<x>543855.5</x>
<y>6537912.2</y>
</ctr>
<cs>2</cs>
<cpoi>
<id>TTR775657</id>
<p>
<x>543855.5</x>
<y>6537912.2</y>
</p>
<ic>9</ic>
<ty>1</ty>
<cs>0</cs>
<d>roadworks</d>
<f>Daussoulx - A4 - E411 (A15)</f>
<t>Fleurus - N29 (A15)</t>
<l>460</l>
<dl>12</dl>
<r>A15/E42</r>
</cpoi>
[...]
<l>11840</l>
</poi>
[...]
</tm>
Query with geometries and original positions
https://api.tomtom.com/traffic/services/4/incidentDetails/s3/6841263.950712,511972.674418,6886056.049288,582676.925582/10/1335294634919/xml?key=Your_Api_Key&language=en&originalPosition=true&geometries=original
XML
<tm id="1400168426640">
<poi>
<id>TTL826194</id>
<p>
<x>581415.6</x>
<y>6535660.9</y>
</p>
<op>
<x>581687.8</x>
<y>6536208.0</y>
</op>
<ic>6</ic>
<ty>3</ty>
<cs>0</cs>
<d>stationary traffic</d>
<f>Rue Joseph Wauters</f>
<t>Rue du Pont</t>
<l>1100</l>
<dl>558</dl>
<r>N90</r>
<v>obob@_`}mKcy@zAe_@kc@</v>
</poi>
<poi>
<id>CLUSTER_489</id>
<p>
<x>545350.3</x>
<y>6538010.8</y>
</p>
<ic>6</ic>
<ty>1</ty>
<cbl>
<x>543311.4</x>
<y>6537799.6</y>
</cbl>
<ctr>
<x>547389.1</x>
<y>6538221.9</y>
</ctr>
<cs>2</cs>
<l>13450</l>
</poi>
[...]
</tm>
HTTP request headers
The following table lists HTTP request headers of particular interest to clients of the Traffic Incident Details API endpoint.
Required headers | |
---|---|
Note: There are no required headers in this endpoint. | |
Optional headers | |
Parameter | Description |
Accept-Encoding |
Contains the content encoding (usually a compression algorithm), that the client is able to understand. Value: gzip
|
Tracking-ID |
Specifies an identifier for the Request.
|
Response data
Successful response
The Incident Details API endpoint for a valid single request returns a response in XML, JSON, or JSONP format.
XML response body example
The following XML code block demonstrates a successful response from the API server.
<?xml version="1.0" encoding="UTF-8"?>
<tm id="1547074766">
<poi>
<id>CLUSTER_33392</id>
<p>
<x>512354.976551</x>
<y>6884986.940485</y>
</p>
<ic>8</ic>
<ty>0</ty>
<cbl>
<x>511745.745125</x>
<y>6884720.789894</y>
</cbl>
<ctr>
<x>513401.986901</x>
<y>6885342.552247</y>
</ctr>
<cs>6</cs>
<l>2696</l>
</poi>
<poi>
<id>CLUSTER_33403</id>
<p>
<x>517237.055551</x>
<y>6870392.648994</y>
</p>
<ic>8</ic>
<ty>0</ty>
<cbl>
<x>515710.491318</x>
<y>6867515.929648</y>
</cbl>
<ctr>
<x>517914.903365</x>
<y>6871902.425883</y>
</ctr>
<cs>4</cs>
<l>411</l>
</poi>
<poi>
<id>CLUSTER_33402</id>
<p>
<x>517150.851569</x>
<y>6881480.091051</y>
</p>
<ic>8</ic>
<ty>0</ty>
<cbl>
<x>516350.492186</x>
<y>6881120.810646</y>
</cbl>
<ctr>
<x>518692.437802</x>
<y>6881832.873844</y>
</ctr>
<cs>3</cs>
<l>1025</l>
</poi>
<poi>
<id>CLUSTER_33423</id>
<p>
<x>529447.048060</x>
<y>6857232.393076</y>
</p>
<ic>9</ic>
<ty>0</ty>
<cbl>
<x>528826.289152</x>
<y>6856307.652093</y>
</cbl>
<ctr>
<x>529833.400081</x>
<y>6858338.803512</y>
</ctr>
<cs>4</cs>
<l>1075</l>
</poi>
<poi>
<id>CLUSTER_33435</id>
<p>
<x>533877.803565</x>
<y>6847601.642198</y>
</p>
<ic>9</ic>
<ty>0</ty>
<cbl>
<x>533583.591781</x>
<y>6847294.516114</y>
</cbl>
<ctr>
<x>534179.588277</x>
<y>6847972.372258</y>
</ctr>
<cs>3</cs>
<l>1311</l>
</poi>
<poi>
<id>CLUSTER_33446</id>
<p>
<x>538577.636873</x>
<y>6863390.768564</y>
</p>
<ic>8</ic>
<ty>0</ty>
<cbl>
<x>538425.877523</x>
<y>6863386.945121</y>
</cbl>
<ctr>
<x>538729.396223</x>
<y>6863394.592007</y>
</ctr>
<cs>2</cs>
<l>410</l>
</poi>
<poi>
<id>CLUSTER_33456</id>
<p>
<x>542265.387307</x>
<y>6856551.318714</y>
</p>
<ic>8</ic>
<ty>0</ty>
<cbl>
<x>541943.148612</x>
<y>6854726.986925</y>
</cbl>
<ctr>
<x>542715.162598</x>
<y>6857564.210354</y>
</ctr>
<cs>3</cs>
<l>440</l>
</poi>
<poi>
<id>CLUSTER_33464</id>
<p>
<x>546234.746514</x>
<y>6868186.871228</y>
</p>
<ic>8</ic>
<ty>0</ty>
<cbl>
<x>543178.243594</x>
<y>6866848.946271</y>
</cbl>
<ctr>
<x>548302.497041</x>
<y>6868941.887530</y>
</ctr>
<cs>7</cs>
<l>1556</l>
</poi>
<poi>
<id>CLUSTER_33462</id>
<p>
<x>545331.140269</x>
<y>6863789.557397</y>
</p>
<ic>8</ic>
<ty>0</ty>
<cbl>
<x>544641.588036</x>
<y>6862180.913406</y>
</cbl>
<ctr>
<x>545889.528685</x>
<y>6865071.521013</y>
</ctr>
<cs>4</cs>
<l>1699</l>
</poi>
<poi>
<id>CLUSTER_33475</id>
<p>
<x>558182.248353</x>
<y>6862716.890855</y>
</p>
<ic>13</ic>
<ty>0</ty>
<cbl>
<x>557855.480057</x>
<y>6861613.063583</y>
</cbl>
<ctr>
<x>558460.553450</x>
<y>6864045.299127</y>
</ctr>
<cs>4</cs>
<l>1741</l>
</poi>
<poi>
<id>CLUSTER_33483</id>
<p>
<x>565149.005750</x>
<y>6852972.834871</y>
</p>
<ic>9</ic>
<ty>0</ty>
<cbl>
<x>563920.280520</x>
<y>6852693.274072</y>
</cbl>
<ctr>
<x>566437.500489</x>
<y>6853356.309469</y>
</ctr>
<cs>3</cs>
<l>4191</l>
</poi>
<poi>
<id>CLUSTER_33494</id>
<p>
<x>573507.430180</x>
<y>6860948.908434</y>
</p>
<ic>8</ic>
<ty>0</ty>
<cbl>
<x>573163.215840</x>
<y>6860188.402379</y>
</cbl>
<ctr>
<x>573766.059820</x>
<y>6861683.260720</y>
</ctr>
<cs>3</cs>
<l>1613</l>
</poi>
<poi>
<id>TTR115943260378400</id>
<p>
<x>529749.372431</x>
<y>6869475.880073</y>
</p>
<ic>9</ic>
<ty>0</ty>
<cs>0</cs>
<d>roadworks</d>
<ed>2019-08-21T19:00:00Z</ed>
<c>new roadworks layout</c>
<f>Halfweg (Amsterdamsestraatweg/N200)</f>
<t>IJmuiden (N200)</t>
<l>2871</l>
<r>N200</r>
<v>uev~Hsm`\?A?M?SC{HCiEEmQGoR?s@Yiw@CeIQkc@GeNCqHAwHA{CCoJCuBCkLCcMAgB@yBAiAAqAAcA?oA@e@@a@By@By@?C</v>
</poi>
<poi>
<id>TTR115952494119200</id>
<p>
<x>534626.495903</x>
<y>6870270.772352</y>
</p>
<ic>9</ic>
<ty>0</ty>
<cs>0</cs>
<d>roadworks</d>
<c>new roadworks layout</c>
<f>IJmuiden (N200)</f>
<t>Halfweg (Amsterdamsestraatweg/N200)</t>
<l>2803</l>
<r>N200</r>
<v>kiv~Ha`i\@pB?V^p@^dAAb@?r@@lG@nEBtLBxF@rDB~IBtKBdG?fB@nEn@bzB^r@FnRDfS</v>
</poi>
<poi>
<id>TTR116303363161648</id>
<p>
<x>557832.961139</x>
<y>6855083.799009</y>
</p>
<ic>9</ic>
<ty>0</ty>
<cs>0</cs>
<d>roadworks</d>
<c>new roadworks layout</c>
<f>Diemen/Driemond (N236)</f>
<t>Weesp (N236)</t>
<l>88</l>
<r>N236</r>
<v>qrf~Hufr]HIBEFUH[DY@]Ba@BSDSLg@No@?Q</v>
</poi>
<poi>
<id>TTR116294132609280</id>
<p>
<x>585903.630533</x>
<y>6865511.636265</y>
</p>
<ic>9</ic>
<ty>0</ty>
<cs>0</cs>
<d>roadworks</d>
<c>new roadworks layout</c>
<f>Almere-Buiten-West - N703 (A6)</f>
<t>Almere-Stedenwijk (A6)</t>
<l>4786</l>
<r>A6</r>
<v>khq~Hmic_@JZ`ApCNd@F|@d@bB\pAf@hBPn@n@|BzC~JnAdEnAjEJZJ\Lb@f@nBx@bDPr@^zAd@|Bl@xCJl@RjAh@~C|@hGLdAXfCb@hDJjAPrBV|Ch@|JHnDBvA@VB|@@p@FlE^~F^fHChAMlGC~@OrCM|COnCKxAI~@SfCm@jGEb@Iv@O~AeAtKUzC_@pEEj@IvAYnEE|@K`COnDAj@IhDCr@?NAd@GvCCtCAZ?^AfJBfEJpHJrDJzD^~IP~BJrABTDh@ZjExAnNx@jHn@jETtA`AvFr@dDl@zCb@lBz@tDBLZjAVbAH\n@pC</v>
</poi>
</tm>
Response field structure
The following table describes XML or JSON element fields that can appear in a response. The types of the fields refer to a JSON response.
Field | Description |
---|---|
<tm> object |
The main Response element.
|
<poi> array |
A single traffic incident, or a cluster of traffic incidents. |
<cpoi> array |
A single incident, only within an expanded cluster. |
<id> string |
The ID of the traffic incident, common among Traffic Incident API services where it is available. |
<p> object |
The point where an icon of the cluster or raw incident should be drawn, expressed in the requested projection.
|
<op> object |
The point representing the actual position of the incident, expressed in the required projection.
originalPosition value is a boolean true. |
<ic> integer |
The icon category associated with this incident. Values are numbers in the range 0-14, with the following meanings:
|
<ty> integer |
The magnitude of delay associated with an incident. Values can be:
|
<cbl> object |
Bottom-left coordinate of the cluster in the projection of the Request. |
<ctr> object |
Top-right coordinate of the cluster in the projection of the Request. |
<cs> integer |
Cluster size: The number of incidents in the cluster. |
<d> string |
Description of the incident in the language requested. |
<sd> string |
Start date of the incident, if available. The date is described in the ISO8601 format. |
<ed> string |
Estimated end date of the incident, if available. The date is described in the ISO8601 format. |
<c> string |
Cause of the incident, if available, in the language requested. |
<f> string |
From: The name of the intersection or location where the traffic due to the incident starts. |
<t> string |
To: The name of the intersection or location where the traffic due to the incident ends. |
<l> integer |
Length of the incident in meters. |
<dl> integer |
Delay caused by the incident in seconds (except in road closures). |
<r> string |
The road number(s) affected by the incident. Multiple road numbers will delimited by slashes. |
<v> string |
A vector representing the geometry of the incident.
|
Error response
If there is an error in the supplied parameters or any other internal problem, an error response is generated in the requested format. If the contentType
parameter could not be parsed, XML will be returned.
Error response field structure
Field | Description |
---|---|
detailedError object |
Main object of the error response. |
code string |
One of a server-defined set of error codes. |
message string |
A human-readable description of the error code. |
Error response JSON example
{
"errorResponse" : {
"@errorCode" : 400,
"@description" : "Invalid style."
},
"detailedError" : {
"code" : "INVALID_REQUEST",
"message" : "Invalid style."
}
}
Error response XML example
<errorResponse description="Invalid style." errorCode="400">
<detailedError>
<code>INVALID_REQUEST</code>
<message>Invalid style.</message>
</detailedError>
</errorResponse>
HTTP response codes
Code | Meaning and Possible Causes |
---|---|
200 |
OK |
400 |
Bad request, usually due to a malformed syntax. |
403 |
Forbidden: The supplied API Key is not valid for this request. |
405 |
Method Not Allowed: The provided HTTP Request method is known by the server, but is not supported by the target resource. |
429 |
Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key. |
500 |
Internal Server Error |
HTTP response headers
The following table lists HTTP response headers of particular interest to clients of the Traffic Incident Details API endpoint.
Header | Description |
---|---|
Access-Control-Allow-Origin |
Indicates that cross-origin resource sharing (CORS) is allowed. Value: * |
Allow |
Lists the set of supported HTTP methods. The header is sent in case a 405 HTTP Response Code is returned.Value: GET, HEAD |
Content-Encoding |
Indicates which encodings were applied to the Response body. Value: gzip
|
Cache-Control |
Contains directives for a caching mechanism. Value: <private, no-cache, no-store, max-age=0, must-revalidate> |
Content-Length |
Contains information about the size of the Response body. Value: <decimal number> |
Content-Type |
Indicates the media type of the resource returned. Value:
|
Content-Language |
Indicates the language of the Response body. Value: <en> |
Date |
Contains the date and time at which the message was originated. Value: <http-date> |
Expires |
Contains the date after which the Response is considered outdated. Value: <http-date> |
TrafficModelID |
Contains the reference value for the state of traffic at a particular time.
|
Tracking-ID |
An identifier for the Request.
|