Traffic Incident Details
Service version: 4
Last edit: 2019.02.21
On this page
Purpose
This service provides information on traffic incidents inside a given bounding box, based on the current Traffic Model ID.
- The Traffic Model ID is available to grant synchronisation of data between calls and API's.
- The Traffic Model ID is a key value for determining the currency of traffic incidents.
- It is updated every minute, and is valid for two minutes before it times out.
- It is used in rendering traffic tiles.
- 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.
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=*****&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=*****
curl command
curl -XGET -H
'http(s)://baseURL/traffic/services/versionNumber/incidentDetails/style/boundingBox/zoom/trafficModelID/format?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. Value: The current value is 4 . |
style string |
The style that will be used to render the traffic tile in the Traffic Incidents Raster or Traffic API. This will have an effect on the coordinates of traffic incidents in the reply. Values:
|
boundingBox float |
The corners of the area to report on, expressed in the projection specified.
Values: |
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 integer |
This is the number-referencing traffic model.
Value: Traffic model ID or |
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 |
Yhe 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.
Default value: |
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).
If this parameter is not used, the Response will not contain a
|
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 EPSG900913 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=*****
<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=*****&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=*****&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>
Response data
Response field structure
The following data table describes all of the XML element fields that can appear in a 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. |
<p> object |
The point where an icon of the cluster or raw incident should be drawn, expressed in the requested projection. This is affected by:
|
<op> object |
The point representing the actual position of the incident, expressed in the required projection. This is only returned if the originalPosition value is a boolean true. |
<ic> integer |
The icon category associated with this incident. Values are numbers in the range 0-13, with the following meanings:
|
<ty> integer |
The magnitude of delay associated with an incident. These values correspond to incident colors in the traffic tiles. 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. |
<c> string |
Cause of the incident, where 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.
|
Errors
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.
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. |
500 |
Internal Server Error |
Response body
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>
<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>
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 |
The API allows cross-origin resource sharing (CORS). Value: * |
Cache-Control |
The API specifies directives for a caching mechanism. Value: <private, no-cache, no-store, max-age=0, must-revalidate> |
Content-Length |
The API contains information about the size of the Response body. Value: <decimal number> |
Content-Type |
The API indicates the media type of the resource returned. Value: <application/json; charset=utf-8> |
Content-Language |
The API indicates the language of the response body. Value: <en> |
Date |
The API contains the date and time at which the message was originated. Value: <http-date> |
Expires |
The API contains the date after which the Response is considered outdated. Value: <http-date> |
TrafficModelID |
Reference value for the state of traffic at a particular time. Value: <numeric> |