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

Vector Incident Tiles

 

Service version: 4
Last edit: 2019.03.13

On this page

Purpose

The Traffic Vector Incidents Tiles API provides data on zoom levels ranging from 0 to 22.

  • For zoom level 0, the world is displayed on a single tile, while at zoom level 22, the world is divided into 244 tiles.
  • See: Zoom Levels and Tile Grid.

The service delivers traffic incidents data packaged in a vector representation of squared sections called vector tiles.

  • Each tile includes a pre-defined collection of road shapes with traffic incidents data.
  • The format of a tile is formally described using the protobuf schema.

Tiles resolution

Roads geometry is stored as coordinates in the range 0-4095. Coordinates (0,0) define the top-left corner of the tile.

Vector format

The Vector format is a binary format created by using Google Protocol Buffers to serialize the data according to this defined vector schema.

  • The data is mapped to protobuf layers called "Traffic incidents flow" and "Traffic incidents POI".
  • Besides the protobuf layers, the protobuf tags are also used to further describe the traffic.

Currently, the following tags are used.

Traffic incidents flow tags
Tag Description
icon_category_[idx] The icon categories associated with this incident.

  • idx - index of the icon_category in ascending priority order starting from 0.
  • Clustering - the idea of clustering is grouping of all overlapping incidents.

If all incidents in the cluster belong to the same type, it will return the incident's type icon.
Otherwise, it will return the cluster icon.
Allowed values:

  • 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.
description_[idx] A description of the incident with the corresponding icon_category idx.
Allowed value: text
delay The delay caused by the incident in seconds (except in road closures).
Allowed value: integer
road_type The tag value describes the road type.
Allowed values:

  • Motorway
  • International road
  • Major road
  • Secondary road
  • Connecting road
  • Major local road
  • Local road
  • Minor local road
  • Non public road
  • Parking road
  • Pedestrian road
  • Walkway road
left_hand_traffic The tag presence indicates if the road has left-hand traffic. If the tag is not present the road has right-hand traffic.
Allowed value: true
magnitude The magnitude of delay associated with the incident.
These values correspond to incident colors in the traffic tiles.
Allowed values:

  • 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.
traffic_road_coverage The tag value describes if the traffic is assigned to the whole road (one way road), or only to one side (two-way road).
Allowed values:

  • one_side
  • full
Traffic incidents POI tags
Tag Description
icon_category_[idx] The icon categories associated with this incident.

  • idx - index of the icon_category in ascending priority order starting from 0.
  • Clustering - the idea of clustering is grouping of all overlapping incidents.

If all incidents in the cluster belong to the same type, it will return the incident's type icon.
Otherwise, it will return the cluster icon.
Allowed values:

  • 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.
description_[idx] A description of the incident with the corresponding icon_category idx.
Allowed value: text
delay The delay caused by the incident in seconds (except in road closures).
Allowed value: integer
road_type The tag value describes the road type.
Allowed values:

  • Motorway
  • International road
  • Major road
  • Secondary road
  • Connecting road
  • Major local road
  • Local road
  • Minor local road
  • Non-public road
  • Parking road
  • Pedestrian road
  • Walkway road
magnitude The magnitude of delay associated with incident. These values correspond to incident colors in the traffic tiles.
Allowed values:

  • 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.
left_hand_traffic The tag presence indicates if the road has left-hand traffic.
If the tag is not present the road has right-hand traffic.
Allowed value: true
traffic_road_coverage The tag value describes if the traffic is assigned to the whole road (one way road), or only to one side (two-way road).
Allowed value:

  • one_side
  • full
poi_type The beginning of incidents is described as start_poi.

  • The ending of incidents is described as end_poi.
  • If the traffic incident has no geometry, it is described as standalone_poi.

Allowed values:

  • start_poi
  • end_poi
  • standalone_poi
heading Describes the direction of the traffic incident.
Allowed value: Degrees, counting clockwise from the north (0° - 360°).
cluster_id The tag presence indicates that the feature is a cluster of POIs.
Allowed value: integer.
clustered The tag presence indicates the incident is clustered. The value of the clustered tag is equal to the ID of the parent cluster.
Allowed value: integer.

Request data

HTTPS method: GET

Note: Communication by both HTTP and HTTPS is supported.

URL format

The generic tile call format is as follows.

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.
http|https://baseURL/traffic/map/versionNumber/tile/incidents/zoom/x/y.format?key=Your_API_Key&t=t

Example

Note: pbf = Protocolbuffer Binary Format

http://api.tomtom.com/traffic/map/4/tile/incidents/5/4/8.pbf?key=Your_API_Key

curl command

curl -XGET 'http://api.tomtom.com/traffic/map/4/tile/incidents/5/4/8.pbf?key=Your_API_Key'

▲ Return to top

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Parameters and values are case-sensitive.
  • Optional parameters 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.
Required parameters
Parameter Description
baseURL
string
The base URL for calling TomTom services.
Value: api.tomtom.com
Other values: [a|b|c|d].api.tomtom.com
See the Host Name Cycling section for details on aliases.
versionNumber
string
The version of the service to call.
Value: The current value is 4.
zoom
integer
The zoom level of the tile to be rendered.
Value: 0..22
x
float
The x coordinate of the tile on the zoom grid.
Value: 0..2 zoom-1
y
float
The y coordinate of the tile on the zoom grid.
Value: 0..2 zoom-1
format
string
The format of the Response.
Value: pbf (Protocolbuffer Binary Format)
key
string
An API Key valid for the requested service.
Value: Your valid API Key.
Optional parameters
Parameter Description
t
string
The reference value for the state of traffic at a particular time, obtained from the Viewport API call.

  • It is updated every minute, and is valid for two minutes before it times out.
  • Use -1 to get the most recent traffic information.
  • This defaults to the most recent traffic information.

Default value: -1 (the most recent traffic information)

▲ Return to top

Host Name Cycling

Most web browsers have a default limitation on the number of active connections that can be allowed to each host.

  • This means if map tiles are being loaded via the api.tomtom.com host name, they will be loaded one at a time.
  • A trick that can be used to get around this limitation is to cycle through the hosts we have created as aliases.
  • These host names are:
    • a.api.tomtom.com
    • b.api.tomtom.com
    • c.api.tomtom.com
    • d.api.tomtom.com
  • By cycling through these four different host names, the web browser will be tricked into retrieving four map tiles at a time rather than just one.
  • This will significantly speed up the performance of map rendering.

For instance, if four map tiles are being requested at zoom level one, you would request the first one as:

http://a.api.tomtom.com/traffic/map/4/tile/incidents/1/0/0.pbf?key=Your_API_Key

The second would be:

http://b.api.tomtom.com/traffic/map/4/tile/incidents/1/0/0.pbf?key=Your_API_Key

and so on up until d.api.tomtom.com. When more than four tiles are being requested, start back again at a.api.tomtom.com.

▲ Return to top

Response data

The Traffic Vector Incidents Tiles API, for a single request, returns a binary Response body which must be deserialized by client code generated by the Google Protocol Buffers compiler.

The following example uses a simple textual representation of the serialized binary vector tile data to illustrate the Response content.

Example Request

http://api.tomtom.com/map/4/tile/incidents/14/8186/5450.pbf?key=Your_API_Key

Example Response

layer: 0
      name: Traffic incident POI
		version: 2
		extent: 4096
		keys:
			0: road_type
			1: traffic_road_coverage
			2: left_hand_traffic
			3: magnitude
			4: icon_category_0
			5: description_0
			6: icon_category_1
			7: description_1
			8: delay
			9: clustered
			10: poi_type
			11: icon_category_2
			12: description_2
			13: heading
		values:
			0: "Major road" [string]
			1: "full" [string]
			2: 1 [bool]
			3: 0 [int]
			4: 7 [int]
			5: "lane closed" [string]
			6: 9 [int]
			7: "roadworks" [string]
			8: 78962 [int]
			9: "start_poi" [string]
			10: "Secondary road" [string]
			11: "one_side" [string]
			12: 1 [bool]
			13: 78941 [int]
			14: 1 [bool]
			15: 3 [int]
			16: 6 [int]
			17: "stationary traffic" [string]
			18: 191 [int]
			19: 1 [bool]
			20: 154.075 [double]
			21: "end_poi" [string]
			22: 1 [bool]
			23: 78959 [int]
			24: 347.705 [double]
		feature: 0
			id: (none)
			geomtype: point
			geometry:
				POINT(3942,20)
			properties:
				road_type="Major road" [string]
				traffic_road_coverage="full" [string]
				left_hand_traffic=1 [bool]
				magnitude=0 [int]
				icon_category_0=7 [int]
				description_0="lane closed" [string]
				icon_category_1=9 [int]
				description_1="roadworks" [string]
				delay=0 [int]
				clustered=78962 [int]
				poi_type="start_poi" [string]
		feature: 1
			id: (none)
			geomtype: point
			geometry:
				POINT(822,-264)
			properties:
				road_type="Secondary road" [string]
				traffic_road_coverage="one_side" [string]
				left_hand_traffic=1 [bool]
				magnitude=0 [int]
				icon_category_0=7 [int]
				description_0="lane closed" [string]
				icon_category_1=9 [int]
				description_1="roadworks" [string]
				delay=0 [int]
				clustered=78941 [int]
				poi_type="start_poi" [string]
		feature: 2
			id: (none)
			geomtype: point
			geometry:
				POINT(782,-12)
			properties:
				road_type="Secondary road" [string]
				traffic_road_coverage="one_side" [string]
				left_hand_traffic=1 [bool]
				magnitude=3 [int]
				icon_category_0=6 [int]
				description_0="stationary traffic" [string]
				icon_category_1=7 [int]
				description_1="lane closed" [string]
				icon_category_2=9 [int]
				description_2="roadworks" [string]
				delay=191 [int]
				clustered=78941 [int]
				poi_type="start_poi" [string]
		feature: 3
			id: (none)
			geomtype: point
			geometry:
				POINT(3906,2)
			properties:
				road_type="Major road" [string]
				traffic_road_coverage="full" [string]
				left_hand_traffic=1 [bool]
				magnitude=0 [int]
				icon_category_0=7 [int]
				description_0="lane closed" [string]
				icon_category_1=9 [int]
				description_1="roadworks" [string]
				delay=0 [int]
				heading=154.075 [double]
				poi_type="end_poi" [string]
		feature: 4
			id: (none)
			geomtype: point
			geometry:
				POINT(3810,-248)
			properties:
				road_type="Major road" [string]
				traffic_road_coverage="full" [string]
				left_hand_traffic=1 [bool]
				magnitude=0 [int]
				icon_category_0=7 [int]
				description_0="lane closed" [string]
				icon_category_1=9 [int]
				description_1="roadworks" [string]
				delay=0 [int]
				clustered=78959 [int]
				heading=347.705 [double]
				poi_type="end_poi" [string]
	layer: 1
		name: Traffic incident flow
		version: 2
		extent: 4096
		keys:
			0: road_type
			1: traffic_road_coverage
			2: left_hand_traffic
			3: magnitude
			4: icon_category_0
			5: description_0
			6: icon_category_1
			7: description_1
			8: delay
			9: clustered
			10: icon_category_2
			11: description_2
		values:
			0: "Major road" [string]
			1: "full" [string]
			2: 1 [bool]
			3: 0 [int]
			4: 7 [int]
			5: "lane closed" [string]
			6: 9 [int]
			7: "roadworks" [string]
			8: "Secondary road" [string]
			9: "one_side" [string]
			10: 1 [bool]
			11: 78941 [int]
			12: 1 [bool]
			13: 3 [int]
			14: 6 [int]
			15: "stationary traffic" [string]
			16: 191 [int]
		feature: 0
			id: (none)
			geomtype: linestring
			geometry:
				LINESTRING[count=14](3809 -409,3800 -310,3808 -260,3810 -254,3814 -216,3818 -198,3820 -190,3822 -182,3834 -156,3838 -146,3852 -114,3878 -54,3892 -30,3906 2)
				LINESTRING[count=95](3446 4505,3456 4478,3490 4384,3504 4350,3508 4332,3516 4304,3540 4212,3546 4188,3584 4016,3594 3964,3600 3916,3608 3846,3610 3756,3610 3746,3610 3718,3608 3648,3606 3576,3606 3524,3604 3460,3602 3402,3602 3374,3602 3338,3602 3284,3596 3184,3596 3170,3594 3156,3588 3052,3582 2974,3578 2932,3572 2878,3572 2860,3566 2816,3566 2804,3562 2748,3558 2728,3556 2710,3556 2698,3556 2606,3556 2528,3558 2472,3556 2406,3560 2294,3562 2252,3564 2196,3566 2178,3568 2128,3582 1952,3596 1754,3598 1714,3606 1616,3610 1556,3612 1494,3616 1440,3618 1426,3622 1380,3628 1332,3628 1322,3636 1208,3646 1114,3648 1086,3660 1008,3670 932,3684 874,3706 794,3728 696,3732 678,3740 640,3764 538,3772 504,3798 442,3832 356,3864 274,3886 218,3888 214,3896 188,3904 166,3910 142,3912 126,3906 108,3906 96,3906 84,3906 58,3906 44,3906 26,3906 2,3892 -30,3878 -54,3852 -114,3838 -146,3834 -156,3822 -182,3820 -190,3818 -198,3814 -216,3810 -248)
				LINESTRING[count=82](3942 20,3930 70,3928 86,3924 112,3912 126,3910 142,3904 166,3896 188,3888 214,3886 218,3864 274,3832 356,3798 442,3772 504,3764 538,3740 640,3732 678,3728 696,3706 794,3684 874,3670 932,3660 1008,3648 1086,3646 1114,3636 1208,3628 1322,3628 1332,3622 1380,3618 1426,3616 1440,3612 1494,3610 1556,3606 1616,3598 1714,3596 1754,3582 1952,3568 2128,3566 2178,3564 2196,3562 2252,3560 2294,3556 2406,3558 2472,3556 2528,3556 2606,3556 2698,3556 2710,3558 2728,3562 2748,3566 2804,3566 2816,3572 2860,3572 2878,3578 2932,3582 2974,3588 3052,3594 3156,3596 3170,3596 3184,3602 3284,3602 3338,3602 3374,3602 3402,3604 3460,3606 3524,3606 3576,3608 3648,3610 3718,3610 3746,3610 3756,3608 3842,3600 3916,3594 3964,3584 4016,3546 4188,3540 4212,3516 4304,3508 4332,3504 4350,3490 4384,3456 4478,3446 4505)
			properties:
				road_type="Major road" [string]
				traffic_road_coverage="full" [string]
				left_hand_traffic=1 [bool]
				magnitude=0 [int]
				icon_category_0=7 [int]
				description_0="lane closed" [string]
				icon_category_1=9 [int]
				description_1="roadworks" [string]
				delay=0 [int]
		feature: 1
			id: (none)
			geomtype: linestring
			geometry:
				LINESTRING[count=2](822 -264,845 -409)
			properties:
				road_type="Secondary road" [string]
				traffic_road_coverage="one_side" [string]
				left_hand_traffic=1 [bool]
				magnitude=0 [int]
				icon_category_0=7 [int]
				description_0="lane closed" [string]
				icon_category_1=9 [int]
				description_1="roadworks" [string]
				delay=0 [int]
				clustered=78941 [int]
		feature: 2
			id: (none)
			geomtype: linestring
			geometry:
				LINESTRING[count=5](782 -12,810 -186,818 -234,822 -262,846 -409)
			properties:
				road_type="Secondary road" [string]
				traffic_road_coverage="one_side" [string]
				left_hand_traffic=1 [bool]
				magnitude=3 [int]
				icon_category_0=6 [int]
				description_0="stationary traffic" [string]
				icon_category_1=7 [int]
				description_1="lane closed" [string]
				icon_category_2=9 [int]
				description_2="roadworks" [string]
				delay=191 [int]
				clustered=78941 [int]
	

HTTP Response codes

Code Meaning and Possible Causes
200 OK
304 Not modified
400 Bad request:

  • The combination of parameters is not supported.
  • zoom n is out of range [0,22]: the requested zoom level is out of the possible range
  • x n is out of range [0,2zoom-1]: The requested x coordinate is out of the possible range.
  • y n is out of range [0,2zoom-1]: The requested y coordinate is out of the possible range.
  • The requested view is not supported.
403 Forbidden: The supplied API Key is not valid for this Request.
500 Internal Server Error: There is a problem with the TomTom Maps Vector Tile service.
503 Service currently unavailable: The service is currently unavailable.
596 Service not found: Unknown version of the service.

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 that gzip compression is supported.
Value: <gzip>
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: <image/pbf>
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>

▲ Return to top