Sorry, you need to enable JavaScript to visit this website.

PricingContact
Traffic API
Get your key

Traffic Incident Details

 

Service version: 4
Last edit: 2019.05.16

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.

  1. Go to the TomTom API Explorer page.
  2. 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.
  3. 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 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:

  • 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		 This is the number-referencing traffic model.

  • This can be obtained from the Viewport API.
  • It is updated every minute, and is valid for two minutes before it times out.
  • If the wrong Traffic Model ID is specified, the correct one will be returned by the interface.
  • A value of -1 will always invoke the most recent traffic model.

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

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

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.
These values correspond to incident colors in the traffic tiles. Values can be:

  • 0: Unknown (shown as grey on traffic tiles)
  • 1: Minor (shown as orange on traffic tiles)
  • 2: Moderate (shown as light red on traffic tiles)
  • 3: Major (shown as dark red on traffic tiles)
  • 4: Undefined (used for road closures and other indefinite delays, shown as grey on traffic tiles)
<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.

  • 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.
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>
      <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 reference value for the state of traffic at a particular time.
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.

Value: <string>

▲ Return to top

You are here

Traffic API / Traffic API Documentation / Traffic Incidents / Traffic Incident Details