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

Vector Incident Tiles

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

TomTom Vector Format

 

TomTom Vector Tile format is a proprietary binary format created by using Google Protocol Buffers to serialize the data according to the schema defined here. 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 Allowed values Description
road_type
  • 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
The tag value describes the road type.
left_hand_traffic
  • true

The tag presence indicates if the road has left hand traffic. If the tag is not present the road has right hand traffic.

magnitude
  • 0 → unknown
  • 1 → minor
  • 2 → moderate
  • 3 → major
  • 4 → undefined

The magnitude of delay associated with the incident. These values correspond to incident colors in the traffic tiles. Values description:

  • unknown: shown as grey on traffic tiles
  • minor: shown as orange on traffic tiles
  • moderate: shown as light red on traffic tiles
  • major: shown as dark red on traffic tiles
  • undefined: used for road closures and other indefinite delays, shown as grey on traffic tiles
traffic_road_coverage
  • one_side
  • full
The tag value describes if the traffic is assigned to the whole road (one way road), or only to one side (two-way road).

Traffic incidents POI tags

Tag Allowed values Description
icon_category_[idx]
  • 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
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.
description_[idx]
  • text
Description of the incident with corresponding icon_category idx.
delay
  • numeric
Delay caused by the incident in seconds (except in road closures).
road_type
  • 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
The tag value describes the road type.
magnitude
  • 0 → unknown
  • 1 → minor
  • 2 → moderate
  • 3 → major
  • 4 → undefined

The magnitude of delay associated with incident. These values correspond to incident colors in the traffic tiles. Values description:

  • unknown: shown as grey on traffic tiles
  • minor: shown as orange on traffic tiles
  • moderate: shown as light red on traffic tiles
  • major: shown as dark red on traffic tiles
  • undefined: used for road closures and other indefinite delays, shown as grey on traffic tiles
left_hand_traffic
  • true

The tag presence indicates if the road has left hand traffic. If the tag is not present the road has right hand traffic.

traffic_road_coverage
  • one_side
  • full
The tag value describes if the traffic is assigned to the whole road (one way road), or only to one side (two-way road).
poi_type
  • standalone_poi
  • start_poi
  • end_poi

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.

heading
  • degrees, counting clockwise from north
    (0° - 360°)

Describes the direction of the traffic incident.

cluster_id
  • value

The tag presence indicates that feature is a cluster of POIs.

clustered
  • value

The tag presence indicates the incident is clustered. The value of the clustered tag is equal to the ID of the parent cluster.

 

Request

Communication by both HTTP and HTTPS is supported.

Format

The generic tile call format is as follows:

<http|https>://<baseURL>/traffic/map/<versionNumber>/tile/incidents/<zoom>/<x>/<y>.<format>?key=<apiKey>[&t=<t>]

Example:

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

Common Parameters

Parameter Description Req'd? Type / Values Default Value
baseURL base URL for calling TomTom services Yes

api.tomtom.com 
[a|b|c|d].api.tomtom.com 
See the Host Name Cycling section for details on aliases.

/versionNumber Version of the service to call. The current version is 4 Yes 4
/zoom Zoom level of tile to be rendered Yes 0..22
/X x coordinate of tile on zoom grid Yes 0..2 zoom -1
/Y y coordinate of tile on zoom grid Yes 0..2 zoom -1
format Format of the response. Yes pbf
key= API Key valid for requested service Yes API Key
t= Reference value for the state of traffic at a particular time, obtained from the Viewport API call. It is valid up to two minutes before it times out. Use -1 to get the most recent traffic information. Default: most recent traffic information. No text -1

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 and 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 speed up performance of map rendering greatly.

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

The second would be:

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

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

For more information go here.

Response

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.

 

Http Response Codes

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

  • combination of parameters is not supported
  • zoom n is out of range 0 <= zoom <= 22: the requested zoom level is out of the possible range
  • n is out of range [0,m]: the requested x coordinate is out of the possible range (the value of m will vary depending on zoom level)
  • n is out of range [0,m]: the requested y coordinate is out of the possible range (the value of m will vary depending on zoom level)
  • requested view is not supported
403 Forbidden: 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.

 

Response Headers

The table below lists HTTP response headers of particular interest to clients of the Traffic Vector Incidents Tiles API.

Header Description Values
Access-Control-Allow-Origin The Traffic Vector Incidents Tiles API allows cross-origin resource sharing (CORS). *
Content-Encoding The Traffic Vector Incidents Tiles API supports gzip compression. <gzip>
Content-Length The Traffic Vector Incidents Tiles API contains information about the size of the response body. <decimal number>
Content-Type The Traffic Vector Incidents Tiles API indicates the media type of the resource returned. <image/pbf>
Date The Traffic Vector Incidents Tiles API contains the date and time at which the message was originated. <Wed, 14 Mar 2018 09:24:21 GMT>
ETag The Traffic Vector Incidents Tiles API contains a specific version of resource. <W/"2fdbd61f30456">
TrafficModelID Reference value for the state of traffic at a particular time. <numeric>