Sorry, you need to enable JavaScript to visit this website.

PricingContact
Traffic API
Get your key

Vector Flow Tiles

The Traffic Vector Flow Tiles API provide 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 flow data packaged in a vector representation of squared sections called vector tiles. Each tile includes pre-defined collection of road shapes with traffic flow data. Format of the tile is formally described using 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

Roads geometry is stored as coordinates in range 0-4095. Coordinates (0,0) define the top left corner of the tile.

TomTom Vector Format

TomTom Vector Tile format is a proprietary binary format created by using Google Protocol Buffers to serialize the data according to the schema defined here. The data is mapped to protobuf layer called "Traffic flow".   Besides the protobuf layers the protobuf tags are also used to further describe the traffic. Currently the following tags are used.

p>Traffic flow tags

 

Tag Allowed values Description
road_type
  • Motorway
  • International road
  • Major road
  • Secondary road
  • Connecting road
  • Major local road
  • Local road
  • Minor local road
  • Non public road
  • Parking road
  • Pedestrian road
  • Walkway road
 The tag value describes the road type.
traffic_level
  • fractional value: 0.00 - 1.00
  • absolute value: greater than or equal to 0

The tag value indicates the traffic speed.

Absolute values in kph are used, when traffic type is set to absolute; fractional values are used, when traffic type is set to relative or relative-delay.

See traffic flow types section for details.
traffic_road_coverage
  • one_side
  • full
 The tag value describes if the traffic is assigned to the whole road (one way road), or only to one side (two-way road).
toll
  • 0

The tag presence indicates if the road is a toll road.

If the tag is not present the road is a toll-free road, if it is present then it holds the toll fee.

Currently the value of the tag does not bring any value, it will always be equal to 0 if tag is set.
travel_mode
  • bridge
  • tunnel
  • skyway
  • ferry
  • rail

The tag presence indicates the existence of one of the following: bridge, tunnel, skyway, ferry by boat (ferry), ferry by rail (rail). If the tag is not present, then the road is a regular road.

Request

Communication by both HTTP and HTTPS is supported.

Format

The generic tile call format is as follows:

<http|https>://<baseURL>/traffic/map/<versionNumber>/tile/flow/<type>/<zoom>/<x>/<y>.<format>?key=<apiKey>

Example:

http://api.tomtom.com/traffic/map/4/tile/flow/relative/5/4/8.pbf?key=<apiKey>

Common Parameters

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

Parameter Description Req'd? Type / Values Default Value
baseURL Base URL for calling TomTom services.
See the Host Name Cycling section for details on aliases.		 Yes

api.tomtom.com 
[a|b|c|d].api.tomtom.com 

 —
versionNumber Version of the service to call. The current version is 1 Yes 4 —
type Types of traffic flow.
See traffic flow types section for details.		 Yes
  • absolute
  • relative
  • relative-delay
 —
zoom Zoom level of tile to be rendered Yes 0..22 —
X x coordinate of tile on zoom grid Yes 0..2 zoom -1 —
Y y coordinate of tile on zoom grid Yes 0..2 zoom -1 —
format Format of the response. Yes pbf —
apiKey API Key valid for requested service Yes API Key —

Types of traffic flow

There are various types of traffic flow to use.

  • absolute reflect the absolute speed
  • relative speed relative to free-flow, highlighting areas of congestion
  • relative-delay relative speed values different from the ones for the freeflow

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 and 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 speed up performance of map rendering greatly.

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

The second would be:

http://b.api.tomtom.com/traffic/map/4/tile/flow/relative/1/0/0.pbf?key=<apiKey>

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

For more information go here.

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.

HTTP Response Codes

Code Meaning and Possible Causes
200 OK
400 Bad request: Probably malformed syntax

  • combination of layer, style and query parameters is not supported
  • zoom n is out of range 0 <= zoom <= 22: the requested zoom level is out of the possible range
  • x n is out of range [0,m]: the requested x coordinate is out of the possible range (the value of m will vary depending on zoom level)
  • y n is out of range [0,m]: the requested y coordinate is out of the possible range (the value of m will vary depending on zoom level)
403 Forbidden: Supplied API key is not valid for this request
500 Internal Server Error: There is a problem with the TomTom Traffic Vector Flow Tiles API
503 Service currently unavailable.

 

Response Headers

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

Header Description Values
Access-Control-Allow-Origin The Traffic Vector Flow Tiles API allows cross-origin resource sharing (CORS). *
Content-Encoding The Traffic Vector Flow Tiles API supports gzip compression. <gzip>
Content-Length The Traffic Vector Flow Tiles API contains information about the size of the response body. <decimal number>
Content-Type The Traffic Vector Flow Tiles API indicates the media type of the resource returned. <image/pbf>
Date The Traffic Vector Flow Tiles API contains the date and time at which the message was originated. <Wed, 14 Mar 2018 09:24:21 GMT>
ETag The Traffic Vector Flow Tiles API contains a specific version of resource. <W/"2fdbd61f30456">
Expires The Traffic Vector Flow Tiles API contains the date after which the response is considered outdated. <http-date>