Vector Flow Tiles

Service version: 4
Last edit: 2022.08.15

Purpose

The Traffic Vector Flow Tiles API 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 244 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 shows either the current speed of traffic on different road segments, or 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.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

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

Currently, the following Traffic flow tags are used.

Default tags

Tag

Description

road_type
string

The tag value describes the road type.
Allowed values:

  • Motorway
  • International road
  • Major road
  • Secondary road
  • Connecting road
  • Major local road
  • Local road
  • Minor local road
  • Non public road
  • Parking road

traffic_level
double

The tag value indicates the traffic speed.

  • Absolute values in kph (kilometers per hour) are used when the traffic type is set to absolute.

  • Fractional values are used when the traffic type is set to relative or relative-delay.

See the traffic flow types section for details.
Allowed values:

  • Fractional value: 0.00 - 1.00

  • Absolute value: Greater than or equal to 0

traffic_road_coverage
string

The tag value describes if the traffic is assigned to the whole road (one way road), or only to one side (two-way road).
Allowed values:

  • one_side

  • full

left_hand_traffic
boolean

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

road_closure
boolean

The tag presence indicates if the road is closed to traffic. If the tag is not present the road is not closed and is passable.
Allowed values: true

On-demand tags

Tag

Description

road_category
string

The tag value describes the road category.
Allowed values:

  • motorway
  • trunk
  • primary
  • secondary
  • tertiary
  • street

road_subcategory
string

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

  • For tertiary road category:

    • connecting
    • major_local
  • For street road category:

    • local
    • minor_local

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.

URL format

get
Generic request URL
https://{baseURL}/traffic/map/{versionNumber}/tile/flow/{type}/{zoom}/{x}/{y}.{format}?key={Your_API_Key}&roadTypes={roadTypes[]}

Example

get
Example
https://api.tomtom.com/traffic/map/4/tile/flow/relative/5/4/8.pbf?key={Your_API_Key}&roadTypes={[2,4,5]}

curl command format

get
curl command
curl 'https://api.tomtom.com/traffic/map/4/tile/flow/relative/5/4/8.pbf?key={Your_API_Key}&roadTypes={[2,4,5]&trafficLevelStep={trafficLevelStep}&margin={margin}&tags={[tags]}'

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.

Required parameters

Description

baseURL
string

The base URL for calling TomTom services.
Values:

versionNumber
string

The version of the service to call.
Value: The current value is 4.

type

Types of traffic flow. See the Traffic flow types section for details.
Value:

  • absolute

  • relative

  • relative-delay

zoom
integer

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

x
integer

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

y
integer

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

Optional parameters

Description

roadTypes
array

The list of values representing the road types, which are going to be displayed on a particular zoom level according to the mapping:

  • 0: Motorway

  • 1: International road

  • 2: Major road

  • 3: Secondary road

  • 4: Connecting road

  • 5: Major local road

  • 6: Local road

  • 7: Minor local road

  • 8: Other roads (Non public road, Parking road, etc.)


The list of values must be enclosed in square brackets [ ], and each value must be separated by a comma. The parameter behaves as a filter, narrowing down the road types displayed for a particular zoom level. If the array of parameters is empty, an empty tile will be sent.
Value: Square brackets [ ] enclosed list/array.

trafficLevelStep
positive float

The step value, describing the minimum difference between values of the traffic_level protobuf tag.
For example:

  • In the case of the relative traffic type, for trafficLevelStep to equal 0.1, the allowed values of traffic_level are: 0.0, 0.1, 0.2.. 1.0

  • In the case of the absolute traffic type, for trafficLevelStep to equal 10, the allowed values of traffic_level are: 0, 10, 20, etc.


Values:

  • for relative and relative-delay traffic types: 0.0 < trafficLevelStep < 1.0

  • for absolute traffic type: 0 < trafficLevelStep

margin
fractional float

The size of the tile margin, relative to the tile size.
Value: 0.0.. 0.1
Default value: 0.1

tags
array

The list of the values representing the available tags in the tile:

  • road_type

  • traffic_level

  • traffic_road_coverage

  • left_hand_traffic

  • road_closure

  • road_category

  • road_subcategory


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

  • The list of the values must be enclosed in square brackets [ ] (an array), and each value must be separated by a comma.

  • The parameter behaves as a filter by narrowing down the list of tags enclosed in each tile. It also allows a decrease in the size of the tile.

  • If the array of parameters is empty, only the geometry will be sent.


Value: Square brackets enclosed list/array.

Types of traffic flow

There are various types of traffic flow to use.

  • absolute: this reflects the absolute speed.
  • relative: this is the speed relative to free-flow, highlighting areas of congestion.
  • relative-delay: this is the speed relative to free-flow (the same as relative), but it only shows areas of high congestion.

Host name cycling

Most web browsers have a default limitation on the number of active connections that can be allowed to each host. This means if map tiles are being loaded via the api.tomtom.com host name, they will be loaded one at a time. A trick that can be used to get around this limitation is to cycle through the hosts we have created as aliases. These host names are:

  • a.api.tomtom.com
  • b.api.tomtom.com
  • c.api.tomtom.com
  • d.api.tomtom.com

By cycling through these four different host names, the web browser will be tricked into retrieving four map tiles at a time rather than just one. This will significantly speed up the performance of map rendering.

For instance, if four map tiles are being requested at zoom level one, you would request the first one as:

get
Request URL using a.api.tomtom.com
https://a.api.tomtom.com/traffic/map/4/tile/flow/relative/1/0/0.pbf?key={Your_API_Key}

The second would be:

get
Request URL using b.api.tomtom.com
https://b.api.tomtom.com/traffic/map/4/tile/flow/relative/1/0/0.pbf?key={Your_API_Key}

and so on up until d.api.tomtom.com. When more than four tiles are being requested, start back again at a.api.tomtom.com.

Request headers

Note: There are no required headers in this endpoint.

Optional headers

Description

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

Absolute Flow Type

get
Request example - Absolute Flow Type
https://api.tomtom.com/map/4/tile/flow/absolute/17/64989/42178.pbf?key={Your_API_Key}
Response example - Absolute Flow Type
1layer: 0
2 name: Traffic flow
3 version: 2
4 extent: 4096
5 keys:
6 0: road_type
7 1: traffic_level
8 2: traffic_road_coverage
9 3: left_hand_traffic
10 values:
11 0: "Major local road" [string]
12 1: 0 [double]
13 2: "one_side" [string]
14 3: 1 [bool]
15 4: "Major road" [string]
16 5: 45 [double]
17 6: 1 [bool]
18 7: 50 [double]
19 8: 1 [bool]
20 feature: 0
21 id: (none)
22 geomtype: linestring
23 geometry:
24 LINESTRING[count=3](3002 -409,2964 1292,2842 2382)
25 LINESTRING[count=3](2842 2382,2964 1292,3002 -409)
26 properties:
27 road_type="Major local road" [string]
28 traffic_level=0 [double]
29 traffic_road_coverage="one_side" [string]
30 left_hand_traffic=1 [bool]
31 feature: 1
32 id: (none)
33 geomtype: linestring
34 geometry:
35 LINESTRING[count=7](4222 4505,4122 4366,3528 3882,3062 3494,2826 2932,2806 2752,2842 2382)
36 LINESTRING[count=8](-409 656,-108 810,1260 1620,1832 1914,2842 2382,3792 2644,4400 2770,4505 2783)
37 properties:
38 road_type="Major road" [string]
39 traffic_level=45 [double]
40 traffic_road_coverage="one_side" [string]
41 left_hand_traffic=1 [bool]
42 feature: 2
43 id: (none)
44 geomtype: linestring
45 geometry:
46 LINESTRING[count=7](2842 2382,2806 2752,2826 2932,3062 3494,3528 3882,4122 4366,4222 4505)
47 LINESTRING[count=10](4505 2766,4418 2752,3882 2660,3406 2552,2920 2430,2700 2308,2276 2114,1952 1958,940 1430,-409 648)
48 properties:
49 road_type="Major road" [string]
50 traffic_level=50 [double]
51 traffic_road_coverage="one_side" [string]
52 left_hand_traffic=1 [bool]

Relative Flow Type

get
Request example - Relative Flow Type
https://api.tomtom.com/map/4/tile/flow/relative/17/64989/42178.pbf?key={Your_API_Key}
Response example - Relative Flow Type
1layer: 0
2 name: Traffic flow
3 version: 2
4 extent: 4096
5 keys:
6 0: road_type
7 1: traffic_level
8 2: traffic_road_coverage
9 3: left_hand_traffic
10 values:
11 0: "Major local road" [string]
12 1: 0 [double]
13 2: "one_side" [string]
14 3: 1 [bool]
15 4: "Major road" [string]
16 5: 0.7 [double]
17 6: 1 [bool]
18 7: 0.767 [double]
19 8: 1 [bool]
20 9: 1 [double]
21 10: 1 [bool]
22 feature: 0
23 id: (none)
24 geomtype: linestring
25 geometry:
26 LINESTRING[count=3](3002 -409,2964 1292,2842 2382)
27 LINESTRING[count=3](2842 2382,2964 1292,3002 -409)
28 properties:
29 road_type="Major local road" [string]
30 traffic_level=0 [double]
31 traffic_road_coverage="one_side" [string]
32 left_hand_traffic=1 [bool]
33 feature: 1
34 id: (none)
35 geomtype: linestring
36 geometry:
37 LINESTRING[count=8](-409 656,-108 810,1260 1620,1832 1914,2842 2382,3792 2644,4400 2770,4505 2783)
38 properties:
39 road_type="Major road" [string]
40 traffic_level=0.7 [double]
41 traffic_road_coverage="one_side" [string]
42 left_hand_traffic=1 [bool]
43 feature: 2
44 id: (none)
45 geomtype: linestring
46 geometry:
47 LINESTRING[count=10](4505 2766,4418 2752,3882 2660,3406 2552,2920 2430,2700 2308,2276 2114,1952 1958,940 1430,-409 648)
48 properties:
49 road_type="Major road" [string]
50 traffic_level=0.767 [double]
51 traffic_road_coverage="one_side" [string]
52 left_hand_traffic=1 [bool]
53 feature: 3
54 id: (none)
55 geomtype: linestring
56 geometry:
57 LINESTRING[count=7](2842 2382,2806 2752,2826 2932,3062 3494,3528 3882,4122 4366,4222 4505)
58 LINESTRING[count=7](4222 4505,4122 4366,3528 3882,3062 3494,2826 2932,2806 2752,2842 2382)
59 properties:
60 road_type="Major local road" [string]
61 traffic_level=1 [double]
62 traffic_road_coverage="one_side" [string]
63 left_hand_traffic=1 [bool]

Relative Delay Flow Type

get
Request example - Relative Delay Flow Type
https://api.tomtom.com/map/4/tile/flow/relative-delay/17/64989/42178.pbf?key={Your_API_Key}
Response example - Relative Delay Flow Type
1layer: 0
2 name: Traffic flow
3 version: 2
4 extent: 4096
5 keys:
6 0: road_type
7 1: traffic_level
8 2: traffic_road_coverage
9 3: left_hand_traffic
10 values:
11 0: "Major local road" [string]
12 1: 0 [double]
13 2: "one_side" [string]
14 3: 1 [bool]
15 4: "Major road" [string]
16 5: 0.694 [double]
17 6: 1 [bool]
18 7: 0.767 [double]
19 8: 1 [bool]
20 feature: 0
21 id: (none)
22 geomtype: linestring
23 geometry:
24 LINESTRING[count=3](3002 -409,2964 1292,2842 2382)
25 LINESTRING[count=3](2842 2382,2964 1292,3002 -409)
26 properties:
27 road_type="Major local road" [string]
28 traffic_level=0 [double]
29 traffic_road_coverage="one_side" [string]
30 left_hand_traffic=1 [bool]
31 feature: 1
32 id: (none)
33 geomtype: linestring
34 geometry:
35 LINESTRING[count=8](-409 656,-108 810,1260 1620,1832 1914,2842 2382,3792 2644,4400 2770,4505 2783)
36 properties:
37 road_type="Major road" [string]
38 traffic_level=0.694 [double]
39 traffic_road_coverage="one_side" [string]
40 left_hand_traffic=1 [bool]
41 feature: 2
42 id: (none)
43 geomtype: linestring
44 geometry:
45 LINESTRING[count=10](4505 2766,4418 2752,3882 2660,3406 2552,2920 2430,2700 2308,2276 2114,1952 1958,940 1430,-409 648)
46 properties:
47 road_type="Major road" [string]
48 traffic_level=0.767 [double]
49 traffic_road_coverage="one_side" [string]
50 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

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 "error": "Invalid zoom value. Allowed values are <0,22>.",
3 "httpStatusCode": 400,
4 "detailedError": {
5 "code": "INVALID_REQUEST",
6 "message": "Invalid zoom value. Allowed values are <0,22>."
7 }
8}

Response codes

Code

Meaning & possible causes

200

OK

400

Bad request:

  • The combination of layer, type, and query 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 Traffic Vector Flow Tiles API endpoint.

503

Service 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 Vector Flow Tiles API endpoint.

Header

Description

Access-Control-Allow-Origin

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

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

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>