Vector Incident Tiles
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
Road geometry is stored as coordinates in the range 0-4095. Coordinates (0,0) define the top-left corner of the tile.
Run this endpoint
You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.
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. The protobuf tags are split into two categories: default and on-demand.
- The default tags are used unless they are filtered out by the
tagsrequest parameter. - The on-demand tags are used only if they were added by the
tagsrequest parameter.
Currently, the following tags are used.
Traffic incidents flow tags
Default tags
Tag | Description |
|---|---|
| The icon categories associated with the single incident.
|
| The icon categories associated with the cluster of incidents.
Allowed values:
|
| A description of the incident with the corresponding
|
| A description of the cluster of incidents with the corresponding
|
| The delay caused by the incident in seconds (except in road closures).
It is calculated against free-flow travel time (the travel time when the
traffic is minimal, e.g., night traffic). |
| The tag value describes the road type.
|
| The tag presence indicates if the road has left-hand traffic. If the tag
is not present the road has right-hand traffic. |
| The magnitude of delay associated with the incident.
|
| The tag value describes if the traffic is assigned to the whole road
(one way road), or only to one side (two-way road).
|
| The tag presence indicates the incident is clustered. The value of the
clustered tag is equal to the ID of the parent cluster. |
On-demand tags
Tag | Description |
|---|---|
| Estimated end date of the incident, when available. The date is
described in
ISO8601 format. |
| The ID of the traffic incident, common among Traffic Incident API
services where it is available. |
| One of the Community Attributes (ACI). An enumeration string specifying
the likelihood of the occurring incident.
|
| One of the Community Attributes (ACI). The number of reports given by
actual end-users. |
| One of the Community Attributes (ACI). |
| The tag value describes the road category.
|
| The tag presence indicates if the road has a subcategory. Not all road
categories have subcategories.
|
Traffic incidents POI tags
Default tags
Tag | Description |
|---|---|
| The icon categories associated with the single incident.
|
| The icon categories associated with the cluster of incidents.
Allowed values:
|
| A description of the incident with the corresponding
|
| A description of the cluster of incidents with the corresponding
|
| The delay caused by the incident in seconds (except in road closures).
It is calculated against free-flow travel time (the travel time when the
traffic is minimal, e.g., night traffic). |
| The tag value describes the road type.
|
| The magnitude of delay associated with the incident.
|
| The tag presence indicates if the road has left-hand traffic. If the tag
is not present the road has right-hand traffic. |
| The tag value describes if the traffic is assigned to the whole road
(one way road), or only to one side (two-way road).
|
| The beginning of incidents is described as
|
| ID of the cluster. The tag presence indicates that the feature is a
cluster of POIs. |
| The number of incidents within a cluster. The tag presence indicates
that the feature is a cluster of POIs. |
| The tag presence indicates the incident is clustered. The value of the
clustered tag is equal to the ID of the parent cluster. |
On-demand tags
Tag | Description |
|---|---|
| Estimated end date of the incident, when available. The date is
described in
ISO8601 format. |
| The ID of the traffic incident, common among Traffic Incident API
services where it is available. |
| One of the Community Attributes (ACI). Enumeration string specifying the
likelihood of the occuring incident.
|
| One of the Community Attributes (ACI). Number of reports given by actual
end-users. |
| One of the Community Attributes (ACI). |
| The tag value describes the road category.
|
| The tag presence indicates if the road has a subcategory. Not all road
categories have subcategories.
|
Request data
HTTPS method: GET
- Constants and parameters enclosed in curly brackets { } must be replaced with their values.
- Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.
URL format
https://{baseURL}/traffic/map/{versionNumber}/tile/incidents/{zoom}/{x}/{y}.{format}?key={Your_API_Key}&t={t}
Example
Note: pbf = Protocolbuffer Binary Format
https://api.tomtom.com/traffic/map/4/tile/incidents/5/4/8.pbf?key={Your_API_Key}
curl command format
curl 'https://api.tomtom.com/traffic/map/4/tile/incidents/5/4/8.pbf?key={Your_API_Key}'
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.
Required parameters | Description |
|---|---|
| The base URL for calling TomTom services.
|
| The version of the service to call. |
| The zoom level of the tile to be rendered. |
| The |
| The |
| The format of the response. |
| An API Key valid for the requested service. |
Optional parameters | Description |
|---|---|
| The Traffic Model ID is the reference
value for the state of traffic at a particular time. Use |
| The list of the values representing the available tags in the tile:
By default, only the default tags are attached to the tile geometry. See Vector format for details.
Value: Square brackets enclosed list. |
| The language code for the output language. Affects the
|
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.comb.api.tomtom.comc.api.tomtom.comd.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:
https://a.api.tomtom.com/traffic/map/4/tile/incidents/1/0/0.pbf?key=Your_API_Key
The second would be:
https://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.
Request headers
The following table lists HTTP request headers of particular interest to clients of the Traffic Vector Incidents Tiles API endpoint. Note: There are no required headers in this endpoint.
Optional headers | Description |
|---|---|
Contains the content encoding (usually a compression algorithm), that
the client is able to understand. | |
Contains an identifier for a specific version of resource. The server
will send back the requested resource, with a 200 HTTP status code, only
if it doesn't have an ETag matching the given one. | |
Tracking-ID | Specifies an identifier for the request.
Value: |
Response data
Successful response
The Traffic Vector Incidents Tiles API endpoint, 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 text representation of the serialized binary vector tile data to illustrate the response content.
Example request
https://api.tomtom.com/map/4/tile/incidents/14/8186/5450.pbf?key={Your_API_Key}
Example response
1layer: 02 name: Traffic incident POI3 version: 24 extent: 40965 keys:6 0: road_type7 1: traffic_road_coverage8 2: left_hand_traffic9 3: magnitude10 4: icon_category_011 5: description_012 6: icon_category_113 7: description_114 8: delay15 9: clustered16 10: poi_type17 11: icon_category_218 12: description_219 values:20 0: "Major road" [string]21 1: "full" [string]22 2: 1 [bool]23 3: 0 [int]24 4: 7 [int]25 5: "lane closed" [string]26 6: 9 [int]27 7: "roadworks" [string]28 8: 78962 [int]29 9: "start_poi" [string]30 10: "Secondary road" [string]31 11: "one_side" [string]32 12: 1 [bool]33 13: 78941 [int]34 14: 1 [bool]35 15: 3 [int]36 16: 6 [int]37 17: "stationary traffic" [string]38 18: 191 [int]39 19: 1 [bool]40 22: 1 [bool]41 23: 78959 [int]42 feature: 043 id: (none)44 geomtype: point45 geometry:46 POINT(3942,20)47 properties:48 road_type="Major road" [string]49 traffic_road_coverage="full" [string]50 left_hand_traffic=1 [bool]51 magnitude=0 [int]52 icon_category_0=7 [int]53 description_0="lane closed" [string]54 icon_category_1=9 [int]55 description_1="roadworks" [string]56 delay=0 [int]57 clustered=78962 [int]58 poi_type="start_poi" [string]59 feature: 160 id: (none)61 geomtype: point62 geometry:63 POINT(822,-264)64 properties:65 road_type="Secondary road" [string]66 traffic_road_coverage="one_side" [string]67 left_hand_traffic=1 [bool]68 magnitude=0 [int]69 icon_category_0=7 [int]70 description_0="lane closed" [string]71 icon_category_1=9 [int]72 description_1="roadworks" [string]73 delay=0 [int]74 clustered=78941 [int]75 poi_type="start_poi" [string]76 feature: 277 id: (none)78 geomtype: point79 geometry:80 POINT(782,-12)81 properties:82 road_type="Secondary road" [string]83 traffic_road_coverage="one_side" [string]84 left_hand_traffic=1 [bool]85 magnitude=3 [int]86 icon_category_0=6 [int]87 description_0="stationary traffic" [string]88 icon_category_1=7 [int]89 description_1="lane closed" [string]90 icon_category_2=9 [int]91 description_2="roadworks" [string]92 delay=191 [int]93 clustered=78941 [int]94 poi_type="start_poi" [string]95 feature: 396 id: (none)97 geomtype: point98 geometry:99 POINT(3906,2)100 properties:101 road_type="Major road" [string]102 traffic_road_coverage="full" [string]103 left_hand_traffic=1 [bool]104 magnitude=0 [int]105 icon_category_0=7 [int]106 description_0="lane closed" [string]107 icon_category_1=9 [int]108 description_1="roadworks" [string]109 delay=0 [int]110 poi_type="standalone_poi" [string]111 feature: 4112 id: (none)113 geomtype: point114 geometry:115 POINT(3810,-248)116 properties:117 road_type="Major road" [string]118 traffic_road_coverage="full" [string]119 left_hand_traffic=1 [bool]120 magnitude=0 [int]121 icon_category_0=7 [int]122 description_0="lane closed" [string]123 icon_category_1=9 [int]124 description_1="roadworks" [string]125 delay=0 [int]126 clustered=78959 [int]127 poi_type="standalone_poi" [string]128 layer: 1129 name: Traffic incident flow130 version: 2131 extent: 4096132 keys:133 0: road_type134 1: traffic_road_coverage135 2: left_hand_traffic136 3: magnitude137 4: icon_category_0138 5: description_0139 6: icon_category_1140 7: description_1141 8: delay142 9: clustered143 10: icon_category_2144 11: description_2145 values:146 0: "Major road" [string]147 1: "full" [string]148 2: 1 [bool]149 3: 0 [int]150 4: 7 [int]151 5: "lane closed" [string]152 6: 9 [int]153 7: "roadworks" [string]154 8: "Secondary road" [string]155 9: "one_side" [string]156 10: 1 [bool]157 11: 78941 [int]158 12: 1 [bool]159 13: 3 [int]160 14: 6 [int]161 15: "stationary traffic" [string]162 16: 191 [int]163 feature: 0164 id: (none)165 geomtype: linestring166 geometry:167 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)168 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)169 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)170 properties:171 road_type="Major road" [string]172 traffic_road_coverage="full" [string]173 left_hand_traffic=1 [bool]174 magnitude=0 [int]175 icon_category_0=7 [int]176 description_0="lane closed" [string]177 icon_category_1=9 [int]178 description_1="roadworks" [string]179 delay=0 [int]180 feature: 1181 id: (none)182 geomtype: linestring183 geometry:184 LINESTRING[count=2](822 -264,845 -409)185 properties:186 road_type="Secondary road" [string]187 traffic_road_coverage="one_side" [string]188 left_hand_traffic=1 [bool]189 magnitude=0 [int]190 icon_category_0=7 [int]191 description_0="lane closed" [string]192 icon_category_1=9 [int]193 description_1="roadworks" [string]194 delay=0 [int]195 clustered=78941 [int]196 feature: 2197 id: (none)198 geomtype: linestring199 geometry:200 LINESTRING[count=5](782 -12,810 -186,818 -234,822 -262,846 -409)201 properties:202 road_type="Secondary road" [string]203 traffic_road_coverage="one_side" [string]204 left_hand_traffic=1 [bool]205 magnitude=3 [int]206 icon_category_0=6 [int]207 description_0="stationary traffic" [string]208 icon_category_1=7 [int]209 description_1="lane closed" [string]210 icon_category_2=9 [int]211 description_2="roadworks" [string]212 delay=191 [int]213 clustered=78941 [int]
Error response
The Traffic Vector Incident Tiles API endpoint for an invalid single request returns a response body in JSON format.
Error response field structure
Field | Description |
|---|---|
| Main object of the error response. |
| One of a server-defined set of error codes. |
| A human-readable description of the error code. |
1{2 "error": "Invalid zoom value. Allowed values are <0,22>.",3 "httpStatusCode": 400,4 "detailedError": {5 "code": "INVALID_REQUEST",6 "message": "Invalid zoom value. Allowed values are <0,22>."7 }8}
Response codes
Code | Meaning & possible causes |
|---|---|
| OK |
| Not modified |
| Bad request:
|
| Forbidden: The supplied API Key is not valid for this request. |
| Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource. |
| Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key. |
| Internal Server Error: There is a problem with the TomTom Maps Vector Tile service. |
| Service currently unavailable: The service is currently unavailable. |
| Service not found: Unknown version of the service. |
Response headers
The following table lists HTTP response headers of particular interest to clients of the Traffic Vector Incidents Tiles API endpoint.
Header | Description |
|---|---|
Indicates that cross-origin resource sharing (CORS) is allowed. | |
Lists the set of supported HTTP methods. The header is sent in case a
| |
Indicates which encodings were applied to the response body. | |
Contains information about the size of the response body. | |
Indicates the media type of the resource returned. | |
Contains the date and time when the message was originated. | |
Contains an identifier for a specific version of resource. | |
Contains the date after which the response is considered outdated. | |
| TrafficModelID | Contains the reference value for the state of traffic at a particular
time. If the request contains a valid Traffic Model ID and is not equal
to |
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. It is only meant to be used for support and does not involve tracking
of you or your users in any form. |