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

PricingContact
Traffic API
Get your key

Traffic Incident Details

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.

Request

Format

http(s)://<baseURL>/traffic/services/<versionNumber>/incidentDetails/<style>/<boundingBox>/<zoom>/<trafficModelID>/<format>?key=<apiKey>[&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=<apiKey>

Parameters

The table below 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, which are highlighted with [square brackets], may be used. If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.

Parameter Description Req'd? Type / Values Default Value
baseURL Base URL for calling the API. Yes api.tomtom.com —
versionNumber Service version number. The current value is 4. Yes 4 —
style 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. Yes
  • s1
  • s2
  • s3
  • night
 —
boundingBox 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. First pair for lower left corner and second for upper right. All values should be separated by commas. Yes minY,minX,maxY,maxX or
minLat,minLon,maxLat,maxLon		 —
zoom Zoom level. This will affect traffic incident coordinates and determine which incidents are included in clusters rather than reported separately. Yes 0 .. 22 —
trafficModelID 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.		 Yes Traffic model ID or -1 —
format 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. Yes
  • xml
  • json
  • jsonp
 —
key Authorization key for access to the API. Yes String —
[language]

ISO 639-1 code for the output language. Affects the <c> (cause) and <d> (description) fields in the response.
Supported languages are 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. (* - deprecated)

When invalid language code is provided response is returned in English. When incident cause or description does not have translation, English description is returned.

 No ISO language code en
[projection] The projection used to specify the coordinates in the request and response. No EPSG900913
[geometries] 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 zoom level) to indicate specific road lanes

If this parameter is not used, the response will not contain a <v> element.

 No
  • original
  • shifted
 —
[expandCluster] List all traffic incidents in a cluster separately. No Boolean false
[originalPosition] Return the original position of the incident (<op>) as well as the one shifted to the beginning of the traffic tube (<p>). No Boolean false
[jsonp] Specifies the callback method. Only used where contentType is jsonp. No String —

An XSD response schema is available for download.

Query with cluster

https://api.tomtom.com/traffic/services/4/incidentDetails/s3/6841263.950712,511972.674418,6886056.049288,582676.925582/11/1335294634919/xml?key=<apiKey>
<tm id="1400168040337">
	<poi>
		<id>europe_CLUSTER_10_-594938581</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>europe_CLUSTER_10_862992325</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=<apiKey>&language=en&expandCluster=true

<tm id="1400168682560">
	<poi>
		<id>europe_HD_BE_TTL826194</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>europe_CLUSTER_10_244993412</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>europe_HD_BE_TTR775657_1</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=<apiKey>&language=en&originalPosition=true&geometries=original

<tm id="1400168426640">
	<poi>
		<id>europe_HD_BE_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>europe_CLUSTER_10_489575083</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

Response Structure

Field Description
<tm> Main response element.
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> A single traffic incident, or a cluster of traffic incidents
<cpoi> A single incident, either on its own or within an expanded cluster
<id> ID of the traffic incident
<p> 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 and road type.
<op> The point representing the actual position of the incident, expressed in the required projection. Only returned if originalPosition is true.
<ic> 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> The magnitude of delay associated with 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> Bottom left coordinate of the cluster in the projection of the request
<ctr> Top right coordinate of the cluster in the projection of the request
<cs> Cluster size: the number of incidents in the cluster
<d> Description of the incident in the language requested.
<c> Cause of the incident, where available, in the language requested.
<f> From: the name of the intersection or location where the traffic due to the incident starts
<t> To: the name of the intersection or location where the traffic due to the incident ends
<l> Length of the incident in meters
<dl> Delay caused by the incident in seconds (except in road closures)
<r> The road number(s) affected by the incident. Multiple road numbers will delimited by slashes.
<v> 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.

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 malformed syntax
403 Forbidden: Supplied API key is not valid for this request
500 Internal Server Error