Vector Flow Tiles

Service version: 1 Last edit: 2024.11.25 TomTom Orbis Maps

Important notes:

This TomTom Orbis API is in Public Preview .
This API is powered by the TomTom Orbis Maps.
See the TomTom Orbis Maps documentation for more information.

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 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_category` string	The tag value describes the road category. Allowed values: `motorway` `motorway_link` `trunk` `trunk_link` `primary` `primary_link` `secondary` `secondary_link` `tertiary` `tertiary_link` `street` `service` `track`
`road_subcategory` string	The tag presence indicates if the road has a subcategory. Not all road categories have subcategories. Allowed values: For the `street` road category: `unclassified` `residential` `living_street` For the `service` road category: `parking` `driveway` `alley`
`relative_speed` double	The tag value indicates the speed relative to free-flow traffic. Allowed values: Fractional value is `0.00` - `1.00`
`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 value: `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 value: `true`

On-demand tags

Tag	Description
`absolute_speed` double	The tag value indicates the absolute speed in kmph (kilometers per hour). Allowed values: Absolute value is greater than or equal to `0`.
`part_of_two_way_road` boolean	The tag presence indicates if the traffic is part of a two-way road (two different geometries, each with a value for one side). If the tag is not present, the flow covers the whole one-way road. Allowed value: `true`
`openlr` string	The OpenLR code describing the flow section. Allowed value: `text`
`display_class` integer	The tag value represents the ranking of the road based on its importance and relevance. It can be used for filtering. Allowed values: `positive integers`

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.

get

URL request format

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

get

URL request example

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

get

curl command request example

1
curl 'https://api.tomtom.com/maps/orbis/traffic//tile/flow/5/4/8.pbf?apiVersion=1&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.

Required parameters	Description
`baseURL` string	The base URL for calling TomTom services. Value: `api.tomtom.com`
`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

Optional parameters	Description
`roadCategoryFilter` string	This filter allows the choice of types of road categories to be included in the response. The filter narrows down the road categories available at a particular zoom level. Multiple values are supported and should be separated by a comma. Default value: all road categories Allowed values: `motorway` `motorway_link` `trunk` `trunk_link` `primary` `primary_link` `secondary` `secondary_link` `tertiary` `tertiary_link` `street` `service` `track`
`tags` array	The list of the values representing the available tags in the tile. Default value: `road_category,road_subcategory,left_hand_traffic,road_closure,relative_speed` Allowed values: `road_category` `road_subcategory` `left_hand_traffic` `road_closure` `relative_speed` `absolute_speed` `part_of_two_way_road` `openlr` `display_class` By default, only the default tags are attached to the tile geometry. See Vector format for details. Each value in the list must be separated by a comma. The parameter behaves as a filter, narrowing down the list of tags enclosed in each tile. The fewer tags chosen, the smaller the tile size because of better geometry merging. Value: Comma-separated list.
`apiVersion` integer	Contains a version of the API to call. Value: The current version is `1`.

roadCategoryFilter
string

This filter allows the choice of types of road categories to be included in the response. The filter narrows down the road categories available at a particular zoom level. Multiple values are supported and should be separated by a comma.
Default value: all road categories
Allowed values:

motorway
motorway_link
trunk
trunk_link
primary
primary_link
secondary
secondary_link
tertiary
tertiary_link
street
service
track

tags
array

The list of the values representing the available tags in the tile.
Default value: road_category,road_subcategory,left_hand_traffic,road_closure,relative_speed
Allowed values:

road_category
road_subcategory
left_hand_traffic
road_closure
relative_speed
absolute_speed
part_of_two_way_road
openlr
display_class

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

Each value in the list must be separated by a comma.
The parameter behaves as a filter, narrowing down the list of tags enclosed in each tile.
The fewer tags chosen, the smaller the tile size because of better geometry merging.

Value: Comma-separated list.

apiVersion
integer

Contains a version of the API to call.
Value: The current version is 1.

Request headers

Required headers	Description
TomTom-Api-Version	Contains a version of the API to call. Value: The current version is `1`.

Optional headers Description

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`

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.

get

Request example

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

Response example

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

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

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 API Vector Flow Tiles 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`
Cache-Control	Contains directives for a caching mechanism. Value: `max-age=<number>`
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"`
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 .I t is only meant to be used for support and does not involve tracking of you or your users in any form. Value: `string`