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

Vector Incident Tiles

 

Service version: 4
Last edit: 2019.02.21

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.

TomTom vector format

The TomTom Vector Tile format is a proprietary 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
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: ID string.
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: ID string.

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=*****&t=t

Example

Note: pbf = Protocolbuffer Binary Format

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

curl command

curl -XGET 'http://api.tomtom.com/traffic/map/4/tile/incidents/5/4/8.pbf?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=*****

The second would be:

http://b.api.tomtom.com/traffic/map/4/tile/incidents/1/0/0.pbf?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=*****

Example Response

layer: 0
      name: Traffic incident flow
      version: 2
      extent: 4096
      keys:
        0: magnitude
        1: road_type
        2: left_hand_traffic
        3: traffic_road_coverage
      values:
        0: 0 [int]
        1: "Secondary road" [string]
        2: 1 [bool]
        3: "one_side" [string]
        4: "Major local road" [string]
        5: 1 [bool]
      feature: 0
        id: (none)
        geomtype: linestring
        geometry:
          LINESTRING[count=7](770 62,772 38,783 -11,810 -185,818 -233,823 -262,847 -409)
        properties:
          magnitude=0 [int]
          road_type="Secondary road" [string]
          left_hand_traffic=1 [bool]
          traffic_road_coverage="one_side" [string]
      feature: 1
        id: (none)
        geomtype: linestring
        geometry:
          LINESTRING[count=3](1213 2037,1187 2034,983 2014)
        properties:
          magnitude=0 [int]
          road_type="Major local road" [string]
          left_hand_traffic=1 [bool]
          traffic_road_coverage="one_side" [string]
    layer: 1
      name: Traffic incident POI
      version: 2
      extent: 4096
      keys:
        0: road_type
        1: left_hand_traffic
        2: traffic_road_coverage
        3: icon_category_0
        4: description_0
        5: icon_category_1
        6: description_1
        7: delay
        8: magnitude
        9: poi_type
        10: heading
      values:
        0: "Secondary road" [string]
        1: 1 [bool]
        2: "one_side" [string]
        3: 7 [int]
        4: "lane closed" [string]
        5: 9 [int]
        6: "roadworks" [string]
        7: 0 [int]
        8: "start_poi" [string]
        9: "Major local road" [string]
        10: 1 [bool]
        11: "single alternate line traffic" [string]
        12: 1 [bool]
        13: "end_poi" [string]
        14: 275.711 [double]
      feature: 0
        id: (none)
        geomtype: point
        geometry:
          POINT(770,62)
        properties:
          road_type="Secondary road" [string]
          left_hand_traffic=1 [bool]
          traffic_road_coverage="one_side" [string]
          icon_category_0=7 [int]
          description_0="lane closed" [string]
          icon_category_1=9 [int]
          description_1="roadworks" [string]
          delay=0 [int]
          magnitude=0 [int]
          poi_type="start_poi" [string]
      feature: 1
        id: (none)
        geomtype: point
        geometry:
          POINT(1213,2037)
        properties:
          road_type="Major local road" [string]
          left_hand_traffic=1 [bool]
          traffic_road_coverage="one_side" [string]
          icon_category_0=7 [int]
          description_0="single alternate line traffic" [string]
          icon_category_1=9 [int]
          description_1="roadworks" [string]
          delay=0 [int]
          magnitude=0 [int]
          poi_type="start_poi" [string]
      feature: 2
        id: (none)
        geomtype: point
        geometry:
          POINT(983,2014)
        properties:
          road_type="Major local road" [string]
          left_hand_traffic=1 [bool]
          traffic_road_coverage="one_side" [string]
          icon_category_0=7 [int]
          description_0="single alternate line traffic" [string]
          icon_category_1=9 [int]
          description_1="roadworks" [string]
          delay=0 [int]
          magnitude=0 [int]
          poi_type="end_poi" [string]
          heading=275.711 [double]

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 <= zoom <= 22: the requested zoom level is out of the possible range
  • x 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 the zoom level).
  • y 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 the zoom level).
  • 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 The Traffic Vector Incidents Tiles API endpoint allows cross-origin resource sharing (CORS).
Value: *
Content-Encoding The Traffic Vector Incidents Tiles API endpoint supports gzip compression.
Value: <gzip>
Content-Length The Traffic Vector Incidents Tiles API endpoint contains information about the size of the Response body.
Value: <decimal number>
Content-Type The Traffic Vector Incidents Tiles API endpoint indicates the media type of the resource returned.
Value: <image/pbf>
Content-Language The Traffic Vector Incidents Tiles API endpoint indicates the language of the response body.
Value: <en>
Date The Traffic Vector Incidents Tiles API endpoint contains the date and time at which the message was originated.
Value: <http-date>
Expires The Traffic Vector Incidents Tiles API endpoint contains the date after which the Response is considered outdated.
Value: <http-date>
TrafficModelID The reference value for the state of traffic at a particular time.
Value: <numeric>

▲ Return to top