Incident Details

Service version: 4
Last edit: 2020.01.14

Purpose

This service provides information on traffic incidents inside 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.
1. Click Try it out.
2. Enter/select all required parameter values and any optional parameter values.
3. 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=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 -XGET -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: `s0` `s0-dark` `s1` `s2` `s3` `night`
`boundingBox` float	The corners of the area to report on, expressed in the projection specified. These are two latitude-longitude pairs describing corners of the bounding box. The first pair is for the lower-left corner and the second pair for the upper-right corner. All values should be separated by commas. If the width or height exceeds maximum size, it is trimmed to the maximum allowed size. See the Maximum bounding box section for details. Values: `minY,minX,maxY,maxX`, or `minLat,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. It can be obtained from the Viewport API. It is updated every minute, and is valid for two minutes before it times out. An invalid value of the Traffic Model ID or a value equal to `-1` always invokes the most recent traffic model. See the Response Headers section for more information. Value: Traffic model ID or `-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: `xml` `json` `jsonp`
`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. Affects the `<c>` (cause) and `<d>` (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. Languages marked with "" are deprecated. Default value:* `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). `original` places incidents precisely on the road. `shifted` moves the incident slightly (depending on the zoom level) to indicate specific road lanes. If this parameter is not used, the Response will not contain a `<v>` element. Values: `original` `shifted`
`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.

▲ Return to top

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 2^zoom x 2^zoom 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 / 2^{zoom - 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>

▲ Return to top

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>

▲ Return to top

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>

▲ Return to top

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. 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 a 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. Value: <string>

▲ Return to top

Response data

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. The attribute `id` is the current traffic model. It may be different than the one in the Request, since the model refreshes every two minutes.
`<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: Traffic style Zoom level Road type
`<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: `0`: Unknown `1`: Accident `2`: Fog `3`: Dangerous Conditions `4`: Rain `5`: Ice `6`: Jam `7`: Lane Closed `8`: Road Closed `9`: Road Works `10`: Wind `11`: Flooding `12`: Detour `13`: Cluster: Returned if a cluster contains incidents with different icon categories.
`<ty>` integer	The magnitude of delay associated with an incident. Values can be: `0`: Unknown `1`: Minor `2`: Moderate `3`: Major `4`: Undefined (used for road closures and other indefinite delays)
`<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.
`<ed>` string	Estimated end date of the incident, when available. The date is described in ISO8601 format.
`<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. Not available for clusters and incidents that do not have a shape/length. Only returned if a valid geometries value is included in the request. The vector is encoded with the Google Encoded Polyline Algorithm.

▲ Return to top

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.
`429`	Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.
`500`	Internal Server Error

▲ Return to top

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>
      <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>

▲ Return to top

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: `*`
`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: `<application/json; charset=utf-8>` `<application/javascript; charset=utf-8>` `<text/xml; charset=utf-8>`
`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. If the Request contains a valid Traffic Model ID and is not equal to `-1`, its value is replicated here. If the Request contains an invalid Traffic Model ID or is equal to `-1`, the most recent one is returned. Value: <numeric>
`Tracking-ID`	An identifier for the Request. If the Tracking-ID header was specified in the Request, it is replicated in the Response. Otherwise, it is generated automatically by the service. For details check RFC 4122. It is only meant to be used for support and does not involve tracking of you or your users in any form. Value: <string>

▲ Return to top

Incident Details

On this page

Purpose

Run this endpoint

Request data

HTTPS method: GET

URL format

Example

curl command

Request parameters

Maximum bounding box

Query with XML cluster

Query with expanded cluster

XML

Query with geometries and original positions

XML

HTTP Request headers

Response data

Response field structure

Errors

HTTP Response codes

Response body

HTTP Response headers

You are here