Vector Incident Tiles

Service version: 2

Last edit: 2026.03.12

TomTom Orbis Maps

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 2⁴⁴ 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 three categories: mandatory, default and on-demand.
- The mandatory tags are included in every response, regardless of any other filtering criteria.
- The default tags are used unless they are filtered out by the tags request parameter (mandatory tags are automatically appended).
- The on-demand tags are used only if they were added by the tags request parameter (mandatory tags are automatically appended).
- The on-demand tags marked as EXPLICIT must be added to tags list explicitly - they are not included automatically when using a wildcard.

Currently, the following tags are used.

Mandatory tags

Tag	Present in the layer	Description
`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`

Default tags

Tag	Present in the layer	Description
`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` `alley`
`icon_category_[idx]` string	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: unknown accident fog dangerousConditions rain ice jam laneClosed roadClosed roadWorks wind flooding brokenDownVehicle
`magnitude_of_delay` string	Traffic incident flow Traffic incident points	The magnitude of delay associated with the incident. Allowed values: unknown minor (slow traffic) moderate (queuing traffic) major (stationary traffic) undefined (road closures, indefinite delays etc.)
`delay_in_seconds` 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`
`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`
`description_[idx]` string	Traffic incident flow Traffic incident points	A description of the incident with the corresponding `icon_category` idx. Allowed value: `text`
`display_class` integer	Traffic incident flow Traffic incident points	The tag value represents the ranking of the road based on its importance and relevance. It can be used for filtering. Allowed values: `positive integers`

On-demand tags

Tag	Present in the layer	Description
`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`
`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`
`time_validity` string	Traffic incident flow Traffic incident points	An enumeration string describing if the incident occurrence is now or in the future. This is the snake_case tile tag `time_validity`, which includes the value in the tile geometry when requested via `tags(time_validity)`. It is distinct from the camelCase `timeValidity` attribute, which filters which incidents are returned. Allowed values: `present` `future`
`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 is measured in km/h within the area marked by an incident. Allowed value: `numeric`
`probability_of_occurrence` string EXPLICIT	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 EXPLICIT	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 EXPLICIT	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`
`openlr` string EXPLICIT	Traffic incident flow Traffic incident points	The OpenLR code describing the incident. Allowed value: `text`

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/incidents/vector/tile/{zoom}/{x}/{y}?apiVersion=2&key={Your_API_Key}

get

URL request example

https://api.tomtom.com/maps/orbis/traffic/incidents/vector/tile/5/4/8?apiVersion=2&key={Your_API_Key}

get

curl command request example

curl 'https://api.tomtom.com/maps/orbis/traffic/incidents/vector/tile/5/4/8?apiVersion=2' -H "TomTom-Api-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
`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...2^zoom-1
`y` integer	The `y` coordinate of the tile on the zoom grid. Value: 0...2^zoom-1
`key` string	An API Key valid for the requested service. Please note that using the `TomTom-Api-Key` header is recommended over the `key` query parameter for improved security. Value: Your valid `API Key`.

Optional parameters	Description
`apiVersion` integer	Contains a version of the API to call. Value: The current version is `2`.
`attributes` string	A list of selected fields to apply on response content, specified in dot-notation. See the Attributes query parameter section for details and examples. Value: list of the selected fields.

Request headers

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

Required headers	Description
TomTom-Api-Key	An API Key valid for the requested service. Preferred method for authentication. Using the header is recommended over the `key` query parameter for improved security. Value: Your valid `API Key`.
TomTom-Api-Version	Contains a version of the API to call. Value: The current version is `2`.

Optional headers	Description
Accept	Advertises which content types, expressed as MIME types, the client is able to understand. In this service, the header is used to specify a preferred response format. If the preferred format is not supported, the server will fall back to the default one. Value: `Accept: application/vnd.mapbox-vector-tile`
Accept-Encoding	Contains the content encoding (usually a compression algorithm), that the client is able to understand. Value: `gzip`
Accept-Language	Contains the language code for the output language. 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.
Attributes	A list of selected fields to apply on response content, specified in dot-notation. See the Attributes header section for details and examples. Value: list of the selected fields.
Attributes-Exclude	A list of selected fields to omit specific content added to the response, specified in dot-notation. See the Attributes-Exclude header section for details and examples. Value: list of the selected fields.
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>`

Attributes

Naming conventions

Tile tag names use snake_case (for example start_time, end_time, time_validity). These are the keys present inside the binary vector tile and the values accepted by tags(...). The camelCase property names returned by the Incident Details endpoint (for example startTime, endTime, timeValidity) do not apply here.

time_validity (tag) and timeValidity (filter) are different things:

time_validity is a snake_case tag — tags(time_validity) includes the value in the tile.

timeValidity is a camelCase attribute filter — attributes=timeValidity(present) (or the Attributes header) selects which incidents are returned.

On this tile endpoint timeValidity is an attributes field, not a standalone query parameter. A bare ?timeValidity=present on the URL is ignored (the default is already present); use the attributes parameter instead. This differs from the Incident Details endpoint, where timeValidity is a genuine query parameter.

Attributes header

A list of selected fields to apply on response content, specified in dot-notation. Nested fields are expressed using . separators and optional grouped subfields using parentheses.
Attributes header must contain at least one valid top-level field. Using only a top-level * wildcard is not allowed.
When a field name refers to a non-primitive object, all its non-EXPLICIT subfields are returned by default unless further restricted in the header. EXPLICIT fields (as documented per API) are only returned when they are explicitly listed in Attributes (they are never included solely by selecting their parent or by using *).
The * wildcard may be used only at non–top-level positions to include all non-EXPLICIT subfields of the selected object.

Syntax:

<field-list> ::= <field> (',' <field>)*
<field> ::= <name> ('.' <field> | <field-set>)?
<field-set> ::= '(' <field-set-list> ')'
<field-set-list> ::= '*' (',' <field>)* | <field> (',' <field>)*
<name> ::= one or more alphabetic characters

Note:

All listed field names must exist in the attributes schema; unknown fields result in an error.
Attributes schema can be found there.
APIs may restrict which fields are allowed in Attributes. Disallowed-but-existing fields result in an error.
New fields may be added over time. When they are marked EXPLICIT, they are not returned unless explicitly requested via Attributes, preserving backward compatibility and performance.
If attributes query parameter is also supported by the endpoint - then it takes precedence over Attributes - Attributes-Exclude header pair.

Examples:

tags.road_category, tags.road_subcategory
tags(road_category, road_subcategory)
tags(road_category, road_subcategory), roadCategories(motorway)
roadCategories.*

Attributes-Exclude header

A list of selected fields to omit specific content added to the response, specified in dot-notation. Nested fields are expressed using . separators and optional grouped subfields using parentheses.
Any field listed in Attributes-Exclude, including its entire sub-tree, is omitted from the response, regardless of whether it was included implicitly or explicitly via the Attributes header. Exclusion always overrules inclusion.
The format of the field list is the same "listed dot-notation" used for the Attributes header:

Syntax:

<field-list> ::= <field> (',' <field>)*
<field> ::= <name> ('.' <field> | <field-set>)?
<field-set> ::= '(' <field-set-list> ')'
<field-set-list> ::= '*' (',' <field>)* | <field> (',' <field>)*
<name> ::= one or more alphabetic characters

Notes:

The exclusion list is applied to the result of the inclusion list. If a parent field is excluded, all of its children are excluded, even if some of those children were explicitly listed in Attributes.
When Attributes header inclusion list is not present in the request, then Attributes-Exclude header value is ignored.
Listed field names in Attributes-Exclude must exist in the attributes schema; unknown fields result in an error.
Attributes schema can be found there.
APIs may restrict which fields are allowed in Attributes-Exclude. Disallowed-but-existing fields result in an error.
Fields may occur multiple times in Attributes-Exclude (not recommended, but not an error).
Some overlap between Attributes and Attributes-Exclude is allowed. In case of overlap, the exclusion takes precedence.
Whether a field is EXPLICIT or not does not change the semantics of exclusion: if it is present in Attributes-Exclude, it is omitted whenever it would otherwise have been returned.
If all fields are excluded, then empty tile is returned.
If attributes query parameter is also supported by the endpoint - then it takes precedence over Attributes - Attributes-Exclude header pair.

Example:
Attributes: roadCategories.*
Attributes-Exclude: roadCategories.motorway_link
Results in all road categories being returned except for the motorway_link.

Attributes query parameter

A list of selected fields to apply on response content, specified in dot-notation. Nested fields are expressed using . separators and optional grouped subfields using parentheses.
attributes query parameter must contain at least one valid top-level field. Using only a top-level * wildcard is not allowed.
When a field name refers to a non-primitive object, all its non-EXPLICIT subfields are returned by default unless further restricted in the query parameter. EXPLICIT fields (as documented per API) are only returned when they are explicitly listed in attributes (they are never included solely by selecting their parent or by using *).
The * wildcard may be used only at non–top-level positions to include all non-EXPLICIT subfields of the selected object.

Syntax:

<field-list> ::= <field> (',' <field>)*
<field> ::= <name> ('.' <field> | <field-set>)?
<field-set> ::= '(' <field-set-list> ')'
<field-set-list> ::= '*' (',' <field>)* | <field> (',' <field>)*
<name> ::= one or more alphabetic characters

Note:

All listed field names must exist in the attributes schema; unknown fields result in an error.
Attributes schema can be found there.
APIs may restrict which fields are allowed in attributes. Disallowed-but-existing fields result in an error.
New fields may be added over time. When they are marked EXPLICIT, they are not returned unless explicitly requested via attributes, preserving backward compatibility and performance.
The attributes query parameter takes precedence over Attributes - Attributes-Exclude header pair.

Examples:

tags.road_category,tags.road_subcategory
tags(road_category,road_subcategory)
tags(road_category,road_subcategory),roadCategories(motorway)
roadCategories.*

Attributes schema

Attribute	Description
`tags`	The list of the values representing the available tags in the tile. Default value: `id,road_category,road_subcategory,icon_category,magnitude_of_delay,delay_in_seconds,left_hand_traffic,description,display_class` Allowed values: `icon_category` (enables `icon_category_[idx]`) `left_hand_traffic` `magnitude_of_delay` `road_category` `road_subcategory` `description` (enables `description_[idx]`) `delay_in_seconds` `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` `display_class` By default, only the default tags are attached to the tile geometry. See Vector format for details. The attribute 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.
`roadCategories`	This attribute allows the choice of types of road categories to be included in the response. The attribute narrows down the road categories available at a particular zoom level. 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`
`iconCategories`	This attribute allows the choice of types of incidents and future incidents to be included in the response. It takes into account the main icon category of the incident. Default values: all incidents types Allowed values: `unknown` `accident` `fog` `dangerousConditions` `rain` `ice` `jam` `laneClosed` `roadClosed` `roadWorks` `wind` `flooding` `brokenDownVehicle`
`timeValidity`	This attribute allows the choice of incidents based on their occurrence in time. It is the camelCase filter `timeValidity`, used inside the `attributes` query parameter (for example `attributes=timeValidity(present)`) or the `Attributes` header. On this tile endpoint it is an attributes field, not a standalone query parameter — a bare `?timeValidity=present` on the URL is ignored (this differs from the Incident Details endpoint, where `timeValidity` is a real query parameter). It is distinct from the snake_case tile tag `time_validity`, which only adds the value to the tile. Default value: `present` Allowed values: `present` `future`

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/incidents/vector/tile/14/8186/5450?&key={Your_API_Key}

Example response

1layer: 0
name: Traffic incident flow
version: 2
extent: 4096
feature: 0
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=2](574 4378,524 4506)
  properties:
    icon_category_0="unknown"
    magnitude_of_delay="unknown"
    road_category="primary"
    left_hand_traffic=1
feature: 1
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=2](1482 4476,1445 4506)
  properties:
    icon_category_0="roadWorks"
    magnitude_of_delay="undefined"
    road_category="tertiary"
    left_hand_traffic=1
feature: 2
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=2](1445 4506,1482 4476)
  properties:
    icon_category_0="roadWorks"
    magnitude_of_delay="undefined"
    road_category="tertiary"
    left_hand_traffic=1
feature: 3
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=2](1482 4476,1445 4506)
  properties:
    icon_category_0="jam"
    icon_category_1="roadWorks"
    magnitude_of_delay="major"
    road_category="tertiary"
    left_hand_traffic=1
feature: 4
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=3](3221 -410,3232 -408,3246 -410)
  properties:
    icon_category_0="jam"
    icon_category_1="roadWorks"
    magnitude_of_delay="major"
    road_category="primary"
    left_hand_traffic=1
feature: 5
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=2](3444 4506,3490 4384)
  properties:
    icon_category_0="roadWorks"
    magnitude_of_delay="undefined"
    road_category="primary"
    left_hand_traffic=1
feature: 6
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=7](3560 2748,3556 2698,3554 2604,3558 2472,3556 2406,3568 2128,3596 1754)
  properties:
    icon_category_0="roadWorks"
    icon_category_1="roadWorks"
    magnitude_of_delay="unknown"
    road_category="primary"
    left_hand_traffic=1
feature: 7
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=6](3628 1322,3612 1494,3582 1952,3568 2128,3556 2406,3558 2472)
  properties:
    icon_category_0="roadWorks"
    magnitude_of_delay="unknown"
    road_category="primary"
    left_hand_traffic=1
feature: 8
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=7](4506 405,4442 364,4364 300,4078 116,4032 88,3976 44,3942 20)
  properties:
    icon_category_0="jam"
    magnitude_of_delay="minor"
    road_category="primary"
    left_hand_traffic=1
feature: 9
  id: (none)
  geomtype: linestring
  geometry:
    LINESTRING[count=7](3942 20,3976 44,4032 88,4078 116,4364 300,4442 364,4506 405)
  properties:
    icon_category_0="jam"
    magnitude_of_delay="moderate"
    road_category="primary"
    left_hand_traffic=1
108layer: 1
name: Traffic incident points
version: 2
extent: 4096
feature: 0
  id: (none)
  geomtype: point
  geometry:
    POINT(574,4378)
properties:
  icon_category_0="roadWorks"
  magnitude_of_delay="unknown"
  road_category="primary"
  left_hand_traffic=1
  point_type="start_point"
feature: 1
  id: (none)
  geomtype: point
  geometry:
    POINT(1482,4476)
  properties:
    icon_category_0="roadWorks"
    magnitude_of_delay="unknown"
    road_category="tertiary"
    left_hand_traffic=1
    point_type="start_point"
feature: 2
  id: (none)
  geomtype: point
  geometry:
    POINT(1482,4476)
  properties:
    icon_category_0="jam"
    icon_category_1="roadWorks"
    magnitude_of_delay="major"
    road_category="tertiary"
    left_hand_traffic=1
    point_type="start_point"
feature: 3
  id: (none)
  geomtype: point
  geometry:
    POINT(3560,2748)
  properties:
    icon_category_0="roadWorks"
    icon_category_1="roadWorks"
    magnitude_of_delay="unknown"
    road_category="primary"
    left_hand_traffic=1
    point_type="start_point"
feature: 4
  id: (none)
  geomtype: point
  geometry:
    POINT(3628,1322)
  properties:
    icon_category_0="roadWorks"
    magnitude_of_delay="unknown"
    road_category="primary"
    left_hand_traffic=1
    point_type="start_point"
feature: 5
  id: (none)
  geomtype: point
  geometry:
    POINT(3942,20)
  properties:
    icon_category_0="jam"
    magnitude_of_delay="moderate"
    road_category="primary"
    left_hand_traffic=1
    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

Field	Description
`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

Code	Meaning & 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,2^zoom-1]: The requested x coordinate is out of the possible range. y n is out of range [0,2^zoom-1]: The requested y coordinate is out of the possible range.
`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.

Header	Description
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`
Cache-Control	Contains directives for a caching mechanism. Value: `max-age=<number>`
Content-Encoding	Indicates which encodings were applied to the response body. Value: `<gzip>`
Content-Language	Contains information about the content language inside the response body. Value: `<language tag>`
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: `application/vnd.mapbox-vector-tile`
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"`
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>`

Vector Incident Tiles

Purpose

Tiles resolution

Vector format

Request data

HTTPS method: GET

Request parameters

Request headers

Attributes

Naming conventions

Attributes header

Attributes-Exclude header

Attributes query parameter

Attributes schema

Response data

Successful response

Error response

Response codes

Response headers

HTTPS method: `GET`