Vector Incident Tiles

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

TagPresent in the layerDescription

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

TagPresent in the layerDescription

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

TagPresent in the layerDescription

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

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 parametersDescription

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 headersDescription
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 headersDescription
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 tagtags(time_validity) includes the value in the tile.
    • timeValidity is a camelCase attribute filterattributes=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

AttributeDescription

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
layer: 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
layer: 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

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
{
"detailedError": {
"code": "INVALID_REQUEST",
"message": "Invalid zoom value. Allowed values are <0,22>."
}
}

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.

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

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>