Developer

Vector Incident Tiles

Service version: 1
Last edit: 2024.11.25
TomTom Orbis Maps

Important notes:

Purpose

The Traffic API Vector Incidents Tiles endpoint 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.

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 incident flow" and "Traffic incident points".
  • 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 tags request parameter.
    • The on-demand tags are used only if they were added by the tags request parameter.

Currently, the following tags are used.

Default tags

TagPresent in the layerDescription

icon_category_[idx]
integer

  • Traffic incident flow
  • Traffic incident points

The icon categories associated with the single incident.
idx - The index of the icon_category in ascending priority order starting from 0.
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
  • 14: Broken Down Vehicle

left_hand_traffic
boolean

  • Traffic incident flow
  • Traffic incident points

The tag presence indicates if the road has left-hand traffic. If the tag if it is not present, the road has right-hand traffic.
Allowed value: true

magnitude_of_delay
integer

  • Traffic incident flow
  • Traffic incident points

The magnitude of delay associated with the incident.
Allowed values:

  • 0: Unknown
  • 1: Minor (slow traffic)
  • 2: Moderate (queuing traffic)
  • 3: Major (stationary traffic)
  • 4: Closed road

road_category
string

  • Traffic incident flow
  • Traffic incident points

The tag value describes the road category.
Allowed values:

  • motorway
  • motorway_link
  • trunk
  • trunk_link
  • primary
  • primary_link
  • secondary
  • secondary_link
  • tertiary
  • tertiary_link
  • street
  • service
  • track

road_subcategory
string

  • Traffic incident flow
  • Traffic incident points

The tag presence indicates if the road has a subcategory. Not all road categories have subcategories.
Allowed values:

  • For the street road category:

    • unclassified
    • residential
    • living_street

  • For the service road category:

    • parking
    • driveway

point_type
string

  • Traffic incident points

The beginning of incidents is described as the start_point. If the traffic incident has no line geometry, it is described as the standalone_point.

  • start_point
  • standalone_point

On-demand tags

TagPresent in the layerDescription

description_[idx]
string

  • Traffic incident flow
  • Traffic incident points

A description of the incident with the corresponding icon_category idx.
Allowed value: text

delay
integer

  • Traffic incident flow
  • Traffic incident points

The tag presence indicates if the incident causes any delay. If the tag is requested, but still it's not present, there is no delay information associated with the incident. The delay value is measured in seconds. It is calculated against free-flow travel time (the travel time when the traffic is minimal, e.g., night traffic).
Allowed value: numeric

part_of_two_way_road
boolean

  • Traffic incident flow
  • Traffic incident points

The tag presence indicates if the traffic is part of a two-way road (two different geometries, each with a value for one side). If the tag is not present, the flow covers the whole one-way road.
Allowed value: true

start_time
string

  • Traffic incident flow
  • Traffic incident points

Start time of the incident, if available. The date is described in ISO8601 format.
Allowed value: value in ISO8601

end_time
string

  • Traffic incident flow
  • Traffic incident points

Estimated end date of the incident, if available. The date is described in ISO8601 format.
Allowed value: value in ISO8601

id
string

  • Traffic incident flow
  • Traffic incident points

The ID of the traffic incident, common among Traffic Incident API services where it is available.
Allowed value: text

probability_of_occurrence
string

  • Traffic incident flow
  • Traffic incident points

One of the Community Attributes (ACI).
This is an enumeration string specifying the likelihood of the occurring incident.
Allowed values:

  • certain
  • probable
  • risk_of
  • improbable

number_of_reports
long integer

  • Traffic incident flow
  • Traffic incident points

One of the Community Attributes (ACI). This is the number of reports given by actual end-users.
Allowed value: numeric

last_report_time
string

  • Traffic incident flow
  • Traffic incident points

One of the Community Attributes (ACI). The date in ISO8601 format, when the last time the incident was reported. It gives the user confidence that the incident is fresh.
Allowed value: value in ISO8601

average_speed_kmph
float

  • Traffic incident flow
  • Traffic incident points

The tag presence indicates if there is average speed information associated with the incident. If the tag is requested, but still it's not present, there is no speed information associated with it. The average speed in measured in km/h within the area marked by an incident.
Allowed value: numeric

openlr
string

  • Traffic incident flow
  • Traffic incident points

The OpenLR code describing the incident.
Allowed value: text

time_validity
string

  • Traffic incident flow
  • Traffic incident points

An enumeration string describing if the incident occurrence is now or in the future.
Allowed values:

  • present
  • future

apiVersion
integer

Contains a version of the API to call. Value: The current version is 1.

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.
get
URL request format
https://{baseURL}/maps/orbis/traffic/tile/incidents/{zoom}/{x}/{y}.{format}?apiVersion=1&key={Your_API_Key}&t={t}

Note: pbf = Protocolbuffer Binary Format

get
URL request example
https://api.tomtom.com/maps/orbis/traffic/tile/incidents/5/4/8.pbf?apiVersion=1&key={Your_API_Key}
get
curl command request example
curl 'https://api.tomtom.com/maps/orbis/traffic/tile/incidents/5/4/8.pbf?apiVersion=1&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 parametersDescription

baseURL
string

The base URL for calling TomTom services.
Value: api.tomtom.com

zoom
integer

The zoom level of the tile to be rendered.
Value: 0...22

x
integer

The x coordinate of the tile on the zoom grid.
Value: 0...2zoom-1

y
integer

The y coordinate of the tile on the zoom grid.
Value: 0...2zoom-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.

version
string

Parameter allowing the use of a new API version for this endpoint.
It will be removed from the API when customers migrate from the old API version.
Value: ver2

Optional parametersDescription

t
string

The Traffic Model ID is the reference value for the state of traffic at a particular time.

Default value: -1

tags
array

The list of the values representing the available tags in the tile.
Default value: icon_category,left_hand_traffic,magnitude_of_delay,road_category,road_subcategory
Allowed values:

  • icon_category (enables icon_category_[idx])
  • left_hand_traffic
  • magnitude_of_delay
  • road_category
  • road_subcategory
  • description (enables description_[idx])
  • delay
  • part_of_two_way_road
  • start_time
  • end_time
  • id
  • probability_of_occurrence
  • number_of_reports
  • last_report_time
  • average_speed_kmph
  • openlr
  • time_validity

By default, only the default tags are attached to the tile geometry. See Vector format for details.

  • Each value in the list must be separated by a comma.
  • The parameter behaves as a filter, narrowing down the list of tags enclosed in each tile.
  • The fewer tags chosen, the smaller the tile size because of better geometry merging.
  • Only tags that are used in both of the two protobuf layers can be used as a parameter value.

Value: Comma-separated list.

roadCategoryFilter
string

This filter allows the choice of types of road categories to be included in the response. The filter narrows down the road categories available at particular zoom level. Multiple values are supported and should be separated by a comma.
Default value: all road categories
Allowed values:

  • motorway
  • motorway_link
  • trunk
  • trunk_link
  • primary
  • primary_link
  • secondary
  • secondary_link
  • tertiary
  • tertiary_link
  • street
  • service
  • track

categoryFilter
string

This filter allows the choice of types of incidents and future incidents to be included in the response. Filtering takes into account the main icon category of the incident. Both value types can be used: numeric and descriptive strings. Multiple values are supported and should be separated by a comma.
Default values: all incidents types
Allowed values:

  • 0: Unknown
  • 1: Accident
  • 2: Fog
  • 3: DangerousConditions
  • 4: Rain
  • 5: Ice
  • 6: Jam
  • 7: LaneClosed
  • 8: RoadClosed
  • 9: RoadWorks
  • 10: Wind
  • 11: Flooding
  • 14: BrokenDownVehicle

timeValidityFilter
string

This filter allows the choice of incidents based on their occurrence in time. Multiple values are supported and they should be separated by a comma.
Default value: present
Allowed values:

  • present
  • future

language
string

The language code for the output language. It affects the description fields in the response. When an incident description does not have a translation, an English description is returned.
Default value: en-GB
Allowed values: List of supported languages.

Request headers

The following table lists HTTP request headers of particular interest to clients of the Traffic Vector Incidents Tiles API endpoint.

Required headersDescription
TomTom-Api-Version

Contains a version of the API to call.
Value: The current version is 1.

Optional headersDescription
Accept-Encoding

Contains the content encoding (usually a compression algorithm), that the client is able to understand.
Value: gzip

If-None-Match

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.
Value: <string>

Tracking-ID

Specifies an identifier for the request.

  • It can be used to trace a call.

  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.

  • An example of the format that matches this regular expression is a UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1).

  • For details check RFC 4122.

  • If specified, it is replicated in the Tracking-ID response header.

  • It is only meant to be used for support and does not involve tracking of you or your users in any form.

Value: <string>

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/maps/orbis/traffic/tile/incidents/14/8186/5450.pbf?&key={Your_API_Key}
Example response
1layer: 0
2  name: Traffic incident flow
3  version: 2
4  extent: 4096
5  feature: 0
6    id: (none)
7    geomtype: linestring
8    geometry:
9      LINESTRING[count=2](574 4378,524 4506)
10    properties:
11      icon_category_0=9
12      magnitude_of_delay=0
13      road_category="primary"
14      left_hand_traffic=1
15  feature: 1
16    id: (none)
17    geomtype: linestring
18    geometry:
19      LINESTRING[count=2](1482 4476,1445 4506)
20    properties:
21      icon_category_0=9
22      magnitude_of_delay=0
23      road_category="tertiary"
24      left_hand_traffic=1
25  feature: 2
26    id: (none)
27    geomtype: linestring
28    geometry:
29      LINESTRING[count=2](1445 4506,1482 4476)
30    properties:
31      icon_category_0=9
32      magnitude_of_delay=0
33      road_category="tertiary"
34      left_hand_traffic=1
35  feature: 3
36    id: (none)
37    geomtype: linestring
38    geometry:
39      LINESTRING[count=2](1482 4476,1445 4506)
40    properties:
41      icon_category_0=6
42      icon_category_1=9
43      magnitude_of_delay=3
44      road_category="tertiary"
45      left_hand_traffic=1
46  feature: 4
47    id: (none)
48    geomtype: linestring
49    geometry:
50      LINESTRING[count=3](3221 -410,3232 -408,3246 -410)
51    properties:
52      icon_category_0=6
53      icon_category_1=9
54      magnitude_of_delay=3
55      road_category="primary"
56      left_hand_traffic=1
57  feature: 5
58    id: (none)
59    geomtype: linestring
60    geometry:
61      LINESTRING[count=2](3444 4506,3490 4384)
62    properties:
63      icon_category_0=9
64      magnitude_of_delay=0
65      road_category="primary"
66      left_hand_traffic=1
67  feature: 6
68    id: (none)
69    geomtype: linestring
70    geometry:
71      LINESTRING[count=7](3560 2748,3556 2698,3554 2604,3558 2472,3556 2406,3568 2128,3596 1754)
72    properties:
73      icon_category_0=9
74      icon_category_1=9
75      magnitude_of_delay=0
76      road_category="primary"
77      left_hand_traffic=1
78  feature: 7
79    id: (none)
80    geomtype: linestring
81    geometry:
82      LINESTRING[count=6](3628 1322,3612 1494,3582 1952,3568 2128,3556 2406,3558 2472)
83    properties:
84      icon_category_0=9
85      magnitude_of_delay=0
86      road_category="primary"
87      left_hand_traffic=1
88  feature: 8
89    id: (none)
90    geomtype: linestring
91    geometry:
92      LINESTRING[count=7](4506 405,4442 364,4364 300,4078 116,4032 88,3976 44,3942 20)
93    properties:
94      icon_category_0=6
95      magnitude_of_delay=1
96      road_category="primary"
97      left_hand_traffic=1
98  feature: 9
99    id: (none)
100    geomtype: linestring
101    geometry:
102      LINESTRING[count=7](3942 20,3976 44,4032 88,4078 116,4364 300,4442 364,4506 405)
103    properties:
104      icon_category_0=6
105      magnitude_of_delay=2
106      road_category="primary"
107      left_hand_traffic=1
108layer: 1
109  name: Traffic incident points
110  version: 2
111  extent: 4096
112  feature: 0
113    id: (none)
114    geomtype: point
115    geometry:
116      POINT(574,4378)
117  properties:
118    icon_category_0=9
119    magnitude_of_delay=0
120    road_category="primary"
121    left_hand_traffic=1
122    point_type="start_point"
123  feature: 1
124    id: (none)
125    geomtype: point
126    geometry:
127      POINT(1482,4476)
128    properties:
129      icon_category_0=9
130      magnitude_of_delay=0
131      road_category="tertiary"
132      left_hand_traffic=1
133      point_type="start_point"
134  feature: 2
135    id: (none)
136    geomtype: point
137    geometry:
138      POINT(1482,4476)
139    properties:
140      icon_category_0=6
141      icon_category_1=9
142      magnitude_of_delay=3
143      road_category="tertiary"
144      left_hand_traffic=1
145      point_type="start_point"
146  feature: 3
147    id: (none)
148    geomtype: point
149    geometry:
150      POINT(3560,2748)
151    properties:
152      icon_category_0=9
153      icon_category_1=9
154      magnitude_of_delay=0
155      road_category="primary"
156      left_hand_traffic=1
157      point_type="start_point"
158  feature: 4
159    id: (none)
160    geomtype: point
161    geometry:
162      POINT(3628,1322)
163    properties:
164      icon_category_0=9
165      magnitude_of_delay=0
166      road_category="primary"
167      left_hand_traffic=1
168      point_type="start_point"
169  feature: 5
170    id: (none)
171    geomtype: point
172    geometry:
173      POINT(3942,20)
174    properties:
175      icon_category_0=6
176      magnitude_of_delay=2
177      road_category="primary"
178      left_hand_traffic=1
179      point_type="start_point"

Error response

The Traffic API Vector Incident Tiles endpoint for an invalid single request returns a response body in JSON format.

Error response field structure

FieldDescription

detailedError
object

Main object of the error response.

code
string

One of a server-defined set of error codes.

message
string

A human-readable description of the error code.
Error response example - JSON
1{
2  "detailedError": {
3    "code": "INVALID_REQUEST",
4    "message": "Invalid zoom value. Allowed values are <0,22>."
5  }
6}

Response codes

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

  • Invalid Traffic Model ID.
403

Forbidden: The supplied API Key is not valid for this request.

405

Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource.

429

Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.

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.

Response headers

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

HeaderDescription
Access-Control-Allow-Origin

Indicates that cross-origin resource sharing (CORS) is allowed.
Value: *

Allow

Lists the set of supported HTTP methods. The header is sent in case a 405 HTTP response code is returned.
Value: GET, HEAD

Content-Encoding

Indicates which encodings were applied to the response body.
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 when the message was originated.
Value: <http-date>

ETag

Contains an identifier for a specific version of resource.
Value: W/"2fdbd61f30456"

Expires

Contains the date after which the response is considered outdated.
Value: <http-date>

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 -1, its value is replicated here.

  • If the request does not contain a Traffic Model ID or it is equal to -1, the most recent one is returned.

Value: <numeric>

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.
Value: <string>