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

Vector Flow Tiles

 

Service version: 4
Last edit: 2019.02.21

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

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

  1. Go to the TomTom API Explorer page.
  2. Click an endpoint.
    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  3. Review the Response.

TomTom Vector format

The 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 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 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
  • Pedestrian road
  • Walkway road
traffic_level 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 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
toll 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 the tag is set.

Allowed value: 0

travel_mode 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.
Allowed values:

  • bridge
  • tunnel
  • skyway
  • ferry
  • rail

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

The generic tile call format is as follows:

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

Example

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

curl command

curl -XGET 'http://api.tomtom.com/traffic/map/4/tile/flow/relative/5/4/8.pbf?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.
  • 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
Other values: [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:

  • 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
Note: There are no optional parameters in this endpoint.

▲ Return to top

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

The second would be:

http://b.api.tomtom.com/traffic/map/4/tile/flow/relative/1/0/0.pbf?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.

▲ Return to top

Response data

The Traffic Vector Incidents 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=*****

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

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

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]

HTTP Response codes

Code Meaning and Possible Causes
200 OK
400 Bad request:

  • The 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 the 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 the zoom level).
403 Forbidden: The 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 endpoint.
503 Service currently unavailable: The service is 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 Incident Details API endpoint.

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

▲ Return to top