Vector Flow Tiles

Purpose

The Traffic API Vector Flow Tiles endpoint provides data on zoom levels ranging from 0 to 22.

• For zoom level 0, the world is displayed on a single tile.
• At zoom level 22, the world is divided into 2⁴⁴ tiles. See the Zoom Levels and Tile Grid .

The service delivers traffic flow data packaged in a vector representation of squared sections called vector tiles.

• Each tile includes a pre-defined collection of road shapes with traffic flow data.
• The format of the tile is formally described using the protobuf schema .

It can show both the current speed of traffic on different road segments, and the difference between current speed and the free-flow speed on the road segment.

Tiles resolution

Road geometry is stored as coordinates in the range of 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 a protobuf layer called “Traffic flow”.
• 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 attribute.
  • The on-demand tags are used only if they were added by the tags attribute.
  • 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 Traffic flow tags are used.

Default tags

On-demand tags

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.

1
https://{baseURL}/maps/orbis/traffic/flow/vector/tile/{zoom}/{x}/{y}?apiVersion=2&key={Your_API_Key}

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

1
curl 'https://api.tomtom.com/maps/orbis/traffic/flow/vector/tile/5/4/8?apiVersion=2' -H "TomTom-Api-Key: {Your_API_Key}"

Request parameters

These elements are used in calls to generate all vector tile layers.

• Required parameters must be used or the call will fail.
• Parameters and values are case-sensitive.
• Optional parameters may be used.

Request headers

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

Response data

Successful response

The Traffic Vector Flow 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 examples use a simple textual representation of the serialized binary vector tile data to illustrate the response content.

1
https://api.tomtom.com/maps/orbis/traffic/flow/vector/tile/17/64989/42178?apiVersion=2&key={Your_API_Key}

1
layer: 0
2
    name: Traffic flow
3
    version: 2
4
    extent: 4096
5
    feature: 0
6
      id: (none)
7
      geomtype: linestring
8
      geometry:
9
        LINESTRING[count=3](3002 -409,2964 1292,2842 2382)
10
        LINESTRING[count=3](2842 2382,2964 1292,3002 -409)
11
      properties:
12
        road_category="primary" [string]
13
        relative_speed=0 [double]
14
        left_hand_traffic=1 [bool]
15
    feature: 1
16
      id: (none)
17
      geomtype: linestring
18
      geometry:
19
        LINESTRING[count=8](-409 656,-108 810,1260 1620,1832 1914,2842 2382,3792 2644,4400 2770,4505 2783)
20
      properties:
21
        road_category="primary" [string]
22
        relative_speed=0.7 [double]
23
        left_hand_traffic=1 [bool]
24
    feature: 2
25
      id: (none)
26
      geomtype: linestring
27
      geometry:
28
        LINESTRING[count=10](4505 2766,4418 2752,3882 2660,3406 2552,2920 2430,2700 2308,2276 2114,1952 1958,940 1430,-409 648)
29
      properties:
30
        road_category="secondary" [string]
31
        relative_speed=0.77 [double]
32
        left_hand_traffic=1 [bool]
33
    feature: 3
34
      id: (none)
35
      geomtype: linestring
36
      geometry:
37
        LINESTRING[count=7](2842 2382,2806 2752,2826 2932,3062 3494,3528 3882,4122 4366,4222 4505)
38
        LINESTRING[count=7](4222 4505,4122 4366,3528 3882,3062 3494,2826 2932,2806 2752,2842 2382)
39
      properties:
40
        road_category="primary" [string]
41
        relative_speed=1 [double]
42
        left_hand_traffic=1 [bool]

Error response

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

Error response field structure

1
{
2
  "detailedError": {
3
    "code": "INVALID_REQUEST",
4
    "message": "Invalid zoom value. Allowed values are <0,22>."
5
  }
6
}

Response codes

Response headers

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