Content

Service version: 2

Last edit: 2023.08.01

Public Preview Notice

This API is in Public Preview. Go to the Public Preview - what is it? page to see what this means.
We welcome your contribution to the development of this version. Please share your observations and suggestions on our forum or send an email to our software engineers.
We appreciate your feedback, and we will keep you posted on how it's used.

TomTom Vector Format

TomTom Vector tiles contain map features (points, lines, road shapes, water polygons, building footprints, etc.) that can be used to visualize map data. The data is divided into multiple protobuf layers. Besides the layers, the protobuf tags are also used to further describe the geographic features.

Legend

Tile

Represents a vector tile as a whole entity. It consists of at least one TileLayer.
If the tile does not contain any relevant data, it contains one layer named empty.

TileLayer

Part of a Tile , representing one of the layers that can be rendered later. One layer consists of e.g., all Parks, Roads, Built-up areas, or Points of interest.

Each TileLayer contains geometries of the same type. A geometry in the vector tile can be one of three types: POINT , LINESTRING , or POLYGON. Every TileLayer contains the following fields:

name
version
extent

It may also contain the following fields:

keys is an array of unique strings.
values is an array of unique TileValues.
features is an array of unique TileFeatures.

Arrays of keys and values contain the mapping for tags of TileFeature.

TileFeature

Member of an array of features stored in a TileLayer , containing a geometry representation that can be rendered.

It always contains the following fields:

type is a type of geometry. It can be POINT , LINESTRING , or POLYGON.
geometry is an array of encoded geometry that can be used for rendering. See the Decoding tile geometry section for details.

It may also contain the following fields:

tags is an array containing properties of feature.
- They are a TileFeature's detailed description which can be used for styling and later rendering the geometry.
- They are encoded into an array of integers.
- In order to decode them, the arrays of keys and values from a corresponding TileLayer must be used.
- See the Decoding feature tile tags section for details.

TileValue

Encoded representation of a string, integer, floating point, or boolean value.

It is stored in a values array, in a TileLayer.
It is used for decoding tags of a TileFeature (together with the members of a keys array).
See the Decoding feature tile tags section for details.

TomTom Vector Schema

Schema data

Formally, the structure of a vector tile is described by the protocol buffer schema. It allows the generation of C++, Java, Python, Go, Ruby, Objective-C, and C# code based on the proto file.

1package vector_tile
2
3option optimize_for = LITE_RUNTIME;
4
5message Tile {
6
enum GeomType {
  UNKNOWN = 0;
  POINT = 1;
  LINESTRING = 2;
  POLYGON = 3;
}
13
message Value {
  optional string string_value = 1;
  optional float float_value = 2;
  optional double double_value = 3;
  optional int64 int_value = 4;
  optional uint64 uint_value = 5;
  optional sint64 sint_value = 6;
  optional bool bool_value = 7;
  extensions 8 to max;
}
24
message Feature {
  optional uint64 id = 1 [ default = 0 ];
  repeated uint32 tags = 2 [ packed = true ];
  optional GeomType type = 3 [ default = UNKNOWN ];
  repeated uint32 geometry = 4 [ packed = true ];
  optional bytes raster = 5;
}
32
message Layer {
  required uint32 version = 15 [ default = 1 ];
  required string name = 1;
  repeated Feature features = 2;
  repeated string keys = 3;
  repeated Value values = 4;
  optional uint32 extent = 5 [ default = 4096 ];
40
  extensions 16 to max;
}
43
repeated Layer layers = 3;
45
extensions 16 to 8191;
47}

Decoding tile geometry

Vector Tile geometry uses the following coordinate system:

Coordinates are always integers.
The (0,0) point is located in the upper-left corner of the tile.
The X axis has values increasing towards the right of the tile.
The Y axis has values increasing towards the bottom of the tile.
The tile may have margin, which is a buffer around the tile in the shape of a square frame. The size of the margin is by default equal to 10% of the width/length of the tile.
The extent is equal to 4096 , so the value range for X and Y coordinates is from 0 to 4095 for visible points.
If the tile has a margin, the coordinates values range is extended by its size in both directions. This may cause coordinate values for points in the left or upper margin to be negative.

Vector Tile geometry is encoded as an array of 32 bit unsigned integers in the geometry array field of the TileFeature.

Encoded format has the following structure:

[command_and_count][x0][y0]..[xn][yn][command_and_count][x0][y0]..

command_and_count contains encoded values of command and count.
[x0][y0]..[xn][yn] are (x,y) coordinate pairs.

Command

The value of command is decoded as follows:

command = command_and_count & 0x7

Commands are to be executed relative to previous path coordinates or the point (0,0) if it is the first command.

Command type	Value	Coordinates	Description
`MoveTo`	`1`	`x,y`	It defines the `(x,y)` coordinate. In the case of a `POINT` type geometry, the coordinate is a new point. In the case of a `LINESTRING` or `POLYGON` type geometry, the coordinate is the start of a new shape.
`LineTo`	`2`	`x,y`	It defines a new segment, starting at the current position of the cursor and ending at the `(x,y)` coordinate. In the case of a `LINESTRING` type geometry, the segment extends the current line. In the case of a `POLYGON` type geometry, the segment extends the current linear ring.
`ClosePath`	`7`	none	It closes the current linear ring of a `POLYGON` type geometry.

Command type

Value

Coordinates

Description

MoveTo

1

x,y

It defines the (x,y) coordinate.

In the case of a POINT type geometry, the coordinate is a new point.
In the case of a LINESTRING or POLYGON type geometry, the coordinate is the start of a new shape.

LineTo

2

x,y

It defines a new segment, starting at the current position of the cursor and ending at the (x,y) coordinate.

In the case of a LINESTRING type geometry, the segment extends the current line.
In the case of a POLYGON type geometry, the segment extends the current linear ring.

ClosePath

7

none

It closes the current linear ring of a POLYGON type geometry.

Count

The value of count is decoded as follows:

count = command_and_count >> 0x3

It defines the n number of [xn][yn] encoded coordinate pairs following the command_and_count value.
These coordinate pairs must be interpreted according to the preceding command type.

Coordinates

Coordinates [x0][y0]..[xn][yn] are encoded in zigzag encoding and are relative to the previous coordinate pair. This means that only the first coordinate pair [x0][y0] in the first command in every TileFeature stores absolute values.

The coordinates are decoded as follows:

1decode(x0) = ((x0 >> 0x1) ^ (-(x0 & 0x1)))
2decode(y0) = ((y0 >> 0x1) ^ (-(y0 & 0x1)))
3
4decode(x1) = decode(x0) + ((x1 >> 0x1) ^ (-(x1 & 0x1)))
5decode(y1) = decode(y0) + ((y1 >> 0x1) ^ (-(y1 & 0x1)))
6
7...
8
9decode(xn) = decode(xn-1) + ((xn >> 0x1) ^ (-(xn & 0x1)))
10decode(yn) = decode(yn-1) + ((yn >> 0x1) ^ (-(yn & 0x1)))

Examples

For a `POINT` type feature:

Input:

1layer: 0
feature: 0
  type: POINT
  geometry: [9, 1136, 6564]

Decoding:

1geometry:
command_and_count = 9
command = 9 & 0x7 = 1
count = 9 >> 0x3 = 1
5
x= 1136, y0 = 6564
decode(x0) = ((1136 >> 0x1) ^ (-(1136 & 0x1))) = 568
decode(y0) = ((6564 >> 0x1) ^ (-(6564 & 0x1))) = 3282

Output:

1layer: 0
2  feature: 0
3  geometry: POINT(561, 3282)

For a `LINESTRING` type feature:

Input:

1layer: 0
  feature: 0
      type: LINESTRING
      geometry: [9, 846, 2312, 10, 652, 1938]

Decoding:

1geometry:
1:
  command_and_count = 9
  command = 9 & 0x7 = 1
  count = 9 >> 0x3 = 1
6
  x0' = 846, y0' = 2312
  decode(x0') = ((846 >> 0x1) ^ (-(846 & 0x1))) = 423
  decode(y0') = ((2312 >> 0x1) ^ (-(2312 & 0x1))) = 1156
2:
  command_and_count = 10
  command = 10 & 0x7 = 2
  count = 10 >> 0x3 = 1
14
  x0 = 652, y0 = 1938
  decode(x0) = decode(x0') + ((x0 >> 0x1) ^ (-(x0 & 0x1)))
  decode(y0) = decode(y0') + ((y0 >> 0x1) ^ (-(y0 & 0x1)))
  decode(x0) = 423 + ((652 >> 0x1) ^ (-(652 & 0x1))) = 749
  decode(y0) = 1156 + ((1938 >> 0x1) ^ (-(1938 & 0x1))) = 2125

Output:

1layer: 0
2  feature: 0
3  geometry: LINESTRING[(423, 1156), (749, 2125)]

For a `POLYGON` type feature:

Input:

1layer: 0
feature: 0
  type: POLYGON
  geometry: [9, 1320, 5622, 26, 416, 707, 68, 612, 483, 96, 7]

Decoding:

1geometry:
1:
  command_and_count = 9
  command = 9 & 0x7 = 1
  count = 9 >> 0x3 = 1
6
  x0' = 1320, y0' = 5622
  decode(x0') = ((1320 >> 0x1) ^ (-(1320 & 0x1))) = 660
  decode(y0') = ((5622 >> 0x1) ^ (-(5622 & 0x1))) = 2811
2:
  command_and_count = 26
  command = 26 & 0x7 = 2
  count = 26 >> 0x3 = 3
14
  x0 = 1736, y0 = 4914
  decode(x0) = decode(x0') + ((416 >> 0x1) ^ (-(416 & 0x1))) = 660 + 208 = 868
  decode(y0) = decode(y0') + ((707 >> 0x1) ^ (-(707 & 0x1))) = 2811 + (-354) = 2457
18
  x1 = 68, y1 = 612
  decode(x1) = decode(x0) + ((68 >> 0x1) ^ (-(68 & 0x1))) = 902
  decode(y1) = decode(y0) + ((612 >> 0x1) ^ (-(612 & 0x1))) = 2763
22
  x2 = 483, y2 = 96
  decode(x2) = decode(x1) + ((483 >> 0x1) ^ (-(483 & 0x1))) = 660
  decode(y2) = decode(y1) + ((96 >> 0x1) ^ (-(96 & 0x1))) = 2811
3:
  command_and_count = 7
  command = 7 & 0x7 = 7
  count = 7 >> 0x3 = 0

Output:

1layer: 0
2  feature: 0
3  geometry: POLYGON[(660, 2811), (868, 2457), (902, 2763), (660, 2811)]

Decoding feature tags

In order to reduce tile size, the properties of each feature are encoded in a tags array.

The tags array contains integer values which are indexes of keys and values arrays belonging to the corresponding layer.
The size of a tags array is always even.
The content of a tags array can be grouped into a list of pairs. Each odd element of an array is the first element of a pair, and each even element of an array is the second element of a pair.
The first element of each pair should be mapped to a keys array.
The second element of each pair should be mapped to a values array.
As a result, we get a decoded list of tags where the first element is the tag name and the second element is the tag value in the form of TileValue.

Example

Below is an example of what an encoded tile may look like.

1layer: 0
keys: ["country_code", "icon_text"],
values: ["SWE", "E4"]
feature: 0
  tags : [0,0,1,1]

After decoding it has to be read like this:

1layer: 0
feature: 0
  properties:
    country_code : "SWE"
    icon_text : "E4"

Tile Layers

The data in TomTom Vector Tiles is organized in layers. The following section provides detailed information about:

Available layers.
Tags that typically appear in features from a given layer.

earth_cover

Earth cover refers to the generalized surface cover of the earth, whether vegetation, sand, ice, or other.

Geometry type: `POLYGON`

earth_cover tags	Values	Description
category string	`cropland` `herbaceous` `ice_and_snow` `sand` `woody`	This tag specifies to which category a given feature belongs.

earth_cover tags

Values

Description

category

string

cropland

herbaceous

ice_and_snow

sand

woody

This tag specifies to which category a given feature belongs.

land_cover

Land cover refers to the surface cover on the ground, whether vegetation, urban infrastructure, or other; it does not describe the use of land, and the use of land may be different for lands with the same cover type. For instance, a land cover type of forest may be used for timber production, wildlife management, or recreation; it might be private land, a protected watershed, or a popular state park.

Geometry type: `POLYGON`

land_cover tags	Values	Description
category string	`beach_or_dune` `moor_or_heathland` `sand`	This tag specifies to which category a given feature belongs.

land_cover tags

Values

Description

category

string

beach_or_dune

moor_or_heathland

sand

This tag specifies to which category a given feature belongs.

land_use

The land use refers to the purpose the land serves, for example, recreation, wildlife habitat or agriculture; it does not describe the surface cover on the ground. For example, a recreational land use could occur in a forest, shrubland, grasslands, or on manicured lawns.

Geometry type: `POLYGON`

land_use tags	Values	Description
category string	`built_up_area` `airport` `cemetery` `city_park` `company` `education` `forest` `golf_course` `grass` `greens` `hospital` `industrial` `institution` `marine_park` `military` `park` `parking` `playing_field` `railway` `reservation` `shopping_center` `stadium` `tourism` `low_emission_zone`	This tag specifies to which category a given feature belongs.
subcategory string	For category `park` : `national` `regional` `state_or_province` `county` For category `marine_park` : `national` `state_or_province` For category `airport` : `ground` `runway` For category `education` : `college_or_university` `school` For category `industrial` : `area` `harbor` For category `military` : `ground` For category `tourism` : `amusement_park` `zoo`	This tag narrows down the category values allowing fine-grained styling and provides a distinction between land uses in the same category.
surface string	For `park` and `playing_field` categories: `grass` `gravel` `paved` `sand`	This tag represents the dominant cover of a land use feature.
protected boolean	For `park` category: `true`	This tag indicates that the selected area is protected.
urban boolean	For `cemetery` , `company` , `hospital` , `industrial` , `institution` , `education` , `shopping_center` , `stadium` and `tourism` categories: `true`	This tag indicates that the selected area is part of an urban area.
leisure boolean	For `city_park` , `playing_field` and `golf_course` categories: `true`	This tag indicates that the selected area is a leisure area.
transportation boolean	For `railway` and `parking` categories: `true`	This tag indicates that the selected area is related to transportation.
vegetation boolean	For `forest` , `grass` and `greens` categories: `true`	This tag indicates that the selected area belongs to the vegetation group.
has_ban boolean	For `low_emission_zone` category: `true`	This tag indicates that there is a zone with a ban regulation. 'Ban' indicates that access to a zone is prohibited when a vehicle matches the characteristics defined in the Emission Regulation. Exceptions may be made for vehicles involved in specific activities, e.g., construction or goods delivery, with appropriate documentation. This restriction cannot be mitigated by paying some charge. This tag only contains a `true` value, otherwise the tag is absent.
has_fee boolean	For `low_emission_zone` category: `true`	This tag indicates that there is a zone with a fee regulation. 'Fee' indicates that access to a zone is allowed upon paying a fee when a vehicle matches the characteristics defined in the Emission Regulation. The fee can be charged on a recurring, short-period basis (e.g., daily or per entry), with the amount often dependent on the vehicle's emission class, e.g., higher polluting vehicles are charged a larger fee. This tag only contains a `true` value, otherwise the tag is absent.
has_license boolean	For `low_emission_zone` category: `true`	This tag indicates that there is a zone with a license plate regulation. This tag only contains a `true` value, otherwise the tag is absent.
allow_category integer	For `low_emission_zone` category: `1` - not allowed `2` - not currently allowed (a time restriction, e.g., not allowed now, but allowed in 1h). `3` - currently allowed (due to a time restriction)	Tag indicates the status of a zone restriction. The lack of this tag means that a zone entry is allowed.
requires_vignette boolean	For `low_emission_zone` category: true	This tag indicates that access to low emission zone is restricted to vehicles that have an officially-issued vignette. This tag only contains a `true` value, otherwise the tag is absent.

land_use tags

Values

Description

category

string

built_up_area

airport

cemetery

city_park

company

education

forest

golf_course

grass

greens

hospital

industrial

institution

marine_park

military

park

parking

playing_field

railway

reservation

shopping_center

stadium

tourism

low_emission_zone

This tag specifies to which category a given feature belongs.

subcategory

string

For category park :

national
regional
state_or_province
county

For category marine_park :

national
state_or_province

For category airport :

ground
runway

For category education :

college_or_university
school

For category industrial :

area
harbor

For category military :

ground

For category tourism :

amusement_park
zoo

This tag narrows down the category values allowing fine-grained styling and provides a distinction between land uses in the same category.

surface

string

For park and playing_field categories:

grass
gravel
paved
sand

This tag represents the dominant cover of a land use feature.

protected

boolean

For park category:

true

This tag indicates that the selected area is protected.

urban

boolean

For cemetery , company , hospital , industrial , institution , education , shopping_center , stadium and tourism categories:

true

This tag indicates that the selected area is part of an urban area.

leisure

boolean

For city_park , playing_field and golf_course categories:

true

This tag indicates that the selected area is a leisure area.

transportation

boolean

For railway and parking categories:

true

This tag indicates that the selected area is related to transportation.

vegetation

boolean

For forest , grass and greens categories:

true

This tag indicates that the selected area belongs to the vegetation group.

has_ban

boolean