Vector Flow Tiles
Service version: 4
Last edit: 2020.12.16
On this page
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 using the TomTom API Explorer.
- Go to the TomTom API Explorer page.
-
Click an endpoint.
- Click Try it out.
- Enter/select all required parameter values and any optional parameter values.
- At the bottom of the form, click Execute.
- Review the Response.
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.
Currently, the following Traffic flow tags are used.
Tag | Description |
---|---|
road_type string |
The tag value describes the road type. Allowed values:
|
traffic_level double |
The tag value indicates the traffic speed.
Allowed values:
|
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:
|
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
|
Request data
HTTPS method: GET
Communication by both HTTP and HTTPS is supported.
URL format
For ease of viewing and identification:
- Required constants and parameters are shown in bold text.
- Optional parameters are shown in normal text.
The generic tile call format is as follows:
http|https://baseURL/traffic/map/versionNumber/tile/flow/type/zoom/x/y.format?key=Your_API_Key&roadTypes=[roadTypes]
Example
http://api.tomtom.com/traffic/map/4/tile/flow/relative/5/4/8.pbf?key=Your_API_Key&roadTypes=[2,4,5]
curl command
curl 'http://api.tomtom.com/traffic/map/4/tile/flow/relative/5/4/8.pbf?key=Your_API_Key&roadTypes=[2,4,5]'
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.
- If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
Required parameters | |
---|---|
Parameter | Description |
baseURL string |
The base URL for calling TomTom services. See the Host Name Cycling section for details on aliases. Value: api.tomtom.com [a|b|c|d].api.tomtom.com |
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:
|
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 | |
Parameter | 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:
[ ] , 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. |
[trafficLevelStep] positive float |
The step value, describing the minimum difference between values of traffic_level protobuf tag.For example:
|
[margin] fractional float |
The size of 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:
|
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
:- The relative speed values are different from the ones for the free-flow. This only highlights areas of 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:
http://a.api.tomtom.com/traffic/map/4/tile/flow/relative/1/0/0.pbf?key=Your_API_Key
The second would be:
http://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.
HTTP request headers
The following table lists HTTP request headers of particular interest to clients of the Traffic Vector Flow Tiles API endpoint.
Required headers | |
---|---|
Note: There are no required headers in this endpoint. | |
Optional headers | |
Parameter | 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 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.
|
Response data
Successful response
The Traffic Vector Flow Tiles API, 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.
Example request - Absolute Flow Type
http://api.tomtom.com/map/4/tile/flow/absolute/17/64989/42178.pbf?key=Your_API_Key
Example response - Absolute Flow Type
layer: 0
name: Traffic flow
version: 2
extent: 4096
keys:
0: road_type
1: traffic_level
2: traffic_road_coverage
3: left_hand_traffic
values:
0: "Major local road" [string]
1: 0 [double]
2: "one_side" [string]
3: 1 [bool]
4: "Major road" [string]
5: 45 [double]
6: 1 [bool]
7: 50 [double]
8: 1 [bool]
feature: 0
id: (none)
geomtype: linestring
geometry:
LINESTRING[count=3](3002 -409,2964 1292,2842 2382)
LINESTRING[count=3](2842 2382,2964 1292,3002 -409)
properties:
road_type="Major local road" [string]
traffic_level=0 [double]
traffic_road_coverage="one_side" [string]
left_hand_traffic=1 [bool]
feature: 1
id: (none)
geomtype: linestring
geometry:
LINESTRING[count=7](4222 4505,4122 4366,3528 3882,3062 3494,2826 2932,2806 2752,2842 2382)
LINESTRING[count=8](-409 656,-108 810,1260 1620,1832 1914,2842 2382,3792 2644,4400 2770,4505 2783)
properties:
road_type="Major road" [string]
traffic_level=45 [double]
traffic_road_coverage="one_side" [string]
left_hand_traffic=1 [bool]
feature: 2
id: (none)
geomtype: linestring
geometry:
LINESTRING[count=7](2842 2382,2806 2752,2826 2932,3062 3494,3528 3882,4122 4366,4222 4505)
LINESTRING[count=10](4505 2766,4418 2752,3882 2660,3406 2552,2920 2430,2700 2308,2276 2114,1952 1958,940 1430,-409 648)
properties:
road_type="Major road" [string]
traffic_level=50 [double]
traffic_road_coverage="one_side" [string]
left_hand_traffic=1 [bool]
Example request - Relative Flow Type
http://api.tomtom.com/map/4/tile/flow/relative/17/64989/42178.pbf?key=Your_API_Key
Example response - Relative Flow Type
layer: 0
name: Traffic flow
version: 2
extent: 4096
keys:
0: road_type
1: traffic_level
2: traffic_road_coverage
3: left_hand_traffic
values:
0: "Major local road" [string]
1: 0 [double]
2: "one_side" [string]
3: 1 [bool]
4: "Major road" [string]
5: 0.7 [double]
6: 1 [bool]
7: 0.767 [double]
8: 1 [bool]
9: 1 [double]
10: 1 [bool]
feature: 0
id: (none)
geomtype: linestring
geometry:
LINESTRING[count=3](3002 -409,2964 1292,2842 2382)
LINESTRING[count=3](2842 2382,2964 1292,3002 -409)
properties:
road_type="Major local road" [string]
traffic_level=0 [double]
traffic_road_coverage="one_side" [string]
left_hand_traffic=1 [bool]
feature: 1
id: (none)
geomtype: linestring
geometry:
LINESTRING[count=8](-409 656,-108 810,1260 1620,1832 1914,2842 2382,3792 2644,4400 2770,4505 2783)
properties:
road_type="Major road" [string]
traffic_level=0.7 [double]
traffic_road_coverage="one_side" [string]
left_hand_traffic=1 [bool]
feature: 2
id: (none)
geomtype: linestring
geometry:
LINESTRING[count=10](4505 2766,4418 2752,3882 2660,3406 2552,2920 2430,2700 2308,2276 2114,1952 1958,940 1430,-409 648)
properties:
road_type="Major road" [string]
traffic_level=0.767 [double]
traffic_road_coverage="one_side" [string]
left_hand_traffic=1 [bool]
feature: 3
id: (none)
geomtype: linestring
geometry:
LINESTRING[count=7](2842 2382,2806 2752,2826 2932,3062 3494,3528 3882,4122 4366,4222 4505)
LINESTRING[count=7](4222 4505,4122 4366,3528 3882,3062 3494,2826 2932,2806 2752,2842 2382)
properties:
road_type="Major local road" [string]
traffic_level=1 [double]
traffic_road_coverage="one_side" [string]
left_hand_traffic=1 [bool]
Example request - Relative Delay Flow Type
http://api.tomtom.com/map/4/tile/flow/relative-delay/17/64989/42178.pbf?key=Your_API_Key
Example response - Relative Delay Flow Type
layer: 0
name: Traffic flow
version: 2
extent: 4096
keys:
0: road_type
1: traffic_level
2: traffic_road_coverage
3: left_hand_traffic
values:
0: "Major local road" [string]
1: 0 [double]
2: "one_side" [string]
3: 1 [bool]
4: "Major road" [string]
5: 0.694 [double]
6: 1 [bool]
7: 0.767 [double]
8: 1 [bool]
feature: 0
id: (none)
geomtype: linestring
geometry:
LINESTRING[count=3](3002 -409,2964 1292,2842 2382)
LINESTRING[count=3](2842 2382,2964 1292,3002 -409)
properties:
road_type="Major local road" [string]
traffic_level=0 [double]
traffic_road_coverage="one_side" [string]
left_hand_traffic=1 [bool]
feature: 1
id: (none)
geomtype: linestring
geometry:
LINESTRING[count=8](-409 656,-108 810,1260 1620,1832 1914,2842 2382,3792 2644,4400 2770,4505 2783)
properties:
road_type="Major road" [string]
traffic_level=0.694 [double]
traffic_road_coverage="one_side" [string]
left_hand_traffic=1 [bool]
feature: 2
id: (none)
geomtype: linestring
geometry:
LINESTRING[count=10](4505 2766,4418 2752,3882 2660,3406 2552,2920 2430,2700 2308,2276 2114,1952 1958,940 1430,-409 648)
properties:
road_type="Major road" [string]
traffic_level=0.767 [double]
traffic_road_coverage="one_side" [string]
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
{
"error" : "Invalid zoom value. Allowed values are .",
"httpStatusCode" : 400,
"detailedError" : {
"code" : "INVALID_REQUEST",
"message" : "Invalid zoom value. Allowed values are ."
}
}
HTTP response codes
Code | Meaning and Possible Causes |
---|---|
200 |
OK |
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 Traffic Vector Flow Tiles API endpoint. |
503 |
Service currently unavailable. |
596 |
Service Not Found: Unknown version of the service. |
HTTP 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 at which 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.
|