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
tagsrequest parameter (mandatory tags are automatically appended). - The on-demand tags are used only if they were added by the
tagsrequest 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 |
|---|---|---|
|
| The ID of the traffic incident, common among Traffic
Incident API services where it is available. |
Default tags
| Tag | Present in the layer | Description |
|---|---|---|
|
| The tag value describes the road category.
|
|
| The tag presence indicates if the road has a subcategory. Not all road categories have subcategories.
|
|
| The icon categories associated with the single incident.
|
|
| The magnitude of delay associated with the incident.
|
|
| 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). |
|
| 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. |
|
| A description of the incident with the corresponding |
|
| The tag value represents the ranking of the road based on its importance and relevance. It can be used for filtering.
Allowed values: |
On-demand tags
| Tag | Present in the layer | Description |
|---|---|---|
|
| 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. |
|
| Start time of the incident, if available.
The date is described in ISO8601 format . |
|
| Estimated end date of the incident, if available.
The date is described in ISO8601 format . |
|
| The beginning of incidents is described as the
|
|
| An enumeration string describing if the incident
occurrence is now or in the future.
|
|
| 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. |
|
| One of the Community Attributes (ACI).
|
|
| One of the Community Attributes (ACI). This is the
number of reports given by actual end-users. |
|
| 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. |
|
| The OpenLR code describing the incident. |
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.
https://{baseURL}/maps/orbis/traffic/incidents/vector/tile/{zoom}/{x}/{y}?apiVersion=2&key={Your_API_Key}https://api.tomtom.com/maps/orbis/traffic/incidents/vector/tile/5/4/8?apiVersion=2&key={Your_API_Key}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 |
|---|---|
| The base URL for calling TomTom services. |
| The zoom level of the tile to be rendered. |
| The |
| The |
| An API Key valid for the requested service. |
| Optional parameters | Description |
|---|---|
| Contains a version of the API to call.
Value: The current version is |
| A list of selected fields to apply on response content, specified in dot-notation. |
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. |
| TomTom-Api-Version | Contains a version of the API to call. |
| 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. |
| Accept-Encoding | Contains the content encoding (usually a compression
algorithm), that the client is able to understand. |
| Accept-Language | Contains the language code for the output language.
Affects the |
| Attributes | A list of selected fields to apply on response content, specified in dot-notation. |
| Attributes-Exclude | A list of selected fields to omit specific content added to the response, specified in dot-notation. |
| 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. |
| Tracking-ID | Specifies an identifier for the request.
Value: |
Attributes
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
attributesquery parameter is also supported by the endpoint - then it takes precedence overAttributes-Attributes-Excludeheader pair.
Examples:
tags.road_category, tags.road_subcategorytags(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
Attributesheader inclusion list is not present in the request, thenAttributes-Excludeheader value is ignored. - Listed field names in
Attributes-Excludemust 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
AttributesandAttributes-Excludeis 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
attributesquery parameter is also supported by the endpoint - then it takes precedence overAttributes-Attributes-Excludeheader 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
attributesquery parameter takes precedence overAttributes-Attributes-Excludeheader pair.
Examples:
tags.road_category,tags.road_subcategorytags(road_category,road_subcategory)tags(road_category,road_subcategory),roadCategories(motorway)roadCategories.*
Attributes schema
| Attribute | Description |
|---|---|
| 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.
|
| 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.
|
| 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.
|
| This attribute allows the choice of incidents based on their
occurrence in time.
|
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=1layer: 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 |
|---|---|
| Main object of the error response. |
| One of a server-defined set of error codes. |
| A human-readable description of the error code. |
{ "detailedError": { "code": "INVALID_REQUEST", "message": "Invalid zoom value. Allowed values are <0,22>." }}Response codes
| Code | Meaning & possible causes |
|---|---|
200 | OK |
304 | Not modified |
400 | Bad request:
|
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. |
| Allow | Lists the set of supported HTTP methods. The header is
sent in case a |
| Cache-Control | Contains directives for a caching mechanism. Value: |
| Content-Encoding | Indicates which encodings were applied to the response body. |
| Content-Language | Contains information about the content language inside the response body.
Value: |
| Content-Length | Contains information about the size of the response body. |
| Content-Type | Indicates the media type of the resource returned. |
| Date | Contains the date and time when the message was originated. |
| ETag | Contains an identifier for a specific version of resource. |
| 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. |