Content

Service version: 1

Last edit: 2023.09.29

TomTom Orbis Maps

Important notes:

This TomTom Orbis API is in public preview.

This API is powered by TomTom Orbis Maps.

See the TomTom Orbis Maps documentation for more information.

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	`woodland` `grassland` `shrubland` `agricultural` `sandy` `bareland`	This tag specifies to which category a given feature belongs.
subcategory string	For category `grassland` : `natural` `managed` For category `agricultural` : `crop_plantation` `tree_plantation` `nursery` For category `sandy` : `sand` `beach` For category `bareland` : `shingle` `mud` `rock`	This tag narrows down the category values allowing fine-grained styling and provides a distinction between land covers in the same category.
primary_tag string	`lsr:` `lds:` `wet:` `ntr:`	Fine-grain attribution of each land cover feature corresponding to the most relevant value found among different feature tags (natural, landuse, boundary, etc...) for more precise filtering or custom styling.
display_class integer	[1, 16]	A numerical value attribute that enables ordering and filtering based on the ranking of the area. The values are in the range 1, 16 inclusive.
wetland boolean	`true`	An attribute depicting whether a feature belongs to a wetland, to enable pattern representation as additional overlay on standard fill symbology.

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
group string	`artificial` `business` `shopping` `transport` `driving` `parking` `healthcare` `education` `outdoor` `leisure` `sport` `lodging` `religion`	This tag specifies to which group a given feature belongs.
category string	For group `artificial` : `urban` `rural` `construction` For group `business` : `industrial` `commercial` For group `transport` : `ground` `station` `airport` For group `outdoor` : `ground` `facility` For group `sport` : `ground` `pitch` For group `lodging` : `camping` `resort` For group `religion` : `place_of_worship` `cemetery`	This tag narrows down the group values allowing fine-grained styling and provides a distinction between land uses in the same group.
primary_tag string	`lds:` `trs:` `lsr:` `amn:` `ptr:` `arw:` `shp:` `rlw:` `hgw:*`	Fine-grain attribution of each feature corresponding to the most relevant value found among different primary tags (leisure, landuse, boundary, etc...) for more precise filtering or custom styling.
display_class integer	[1, 16]	A numerical value attribute that enables ordering and filtering based on the ranking of the area. The values are in the range 1, 16 inclusive.
underground boolean	`true`	Indicates that area is an underground areas, such as subway platform, parking, etc...
modality string	`aerial` `rail` `tram` `bus` `subway` `ferry` `taxi`	Attribution to qualify the main mobility type of a passenger transportation feature.
profile string	`vehicle` `motorcycle` `bicycle`	Indicates main profile of use of an area.

structures

Features in this layer represent man-made structures.

Geometry type: `POLYGON`

structures tags	Values	Description
category string	`bridge` `pier` `water_barrier`	Provides macro-classification based on the main type of structure.
subcategory string	For category `water_barrier` : `breakwater` `groyne`	Provides fine-grained classification based on the specific function of the structure to enable filtering depending on the use case.
z_level integer	[-5, 5]	The integer value used to determine the drawing order of overlapping structure segments. The values are in the range -5, 5 inclusive.

structures tags

Values

Description

category

string

bridge
pier
water_barrier

Provides macro-classification based on the main type of structure.

subcategory

string

For category water_barrier :

breakwater
groyne

Provides fine-grained classification based on the specific function of the structure to enable filtering depending on the use case.

z_level

integer

[-5, 5]

The integer value used to determine the drawing order of overlapping structure segments. The values are in the range -5, 5 inclusive.

structures_lines

Features in this layer represent man-made structure lines.

Geometry type: `LINESTRING`

structures_lines tags	Values	Description
category string	`pier` `water_barrier`	Provides macro-classification based on the main type of structure.
subcategory string	For category `water_barrier` : `breakwater` `groyne`	Provides fine-grained classification based on the specific function of the structure to enable filtering depending on the use case.
z_level integer	[-5, 5]	The integer value used to determine the drawing order of overlapping structure segments. The values are in the range -5, 5 inclusive.

structures_lines tags

Values

Description

category

string

pier
water_barrier

Provides macro-classification based on the main type of structure.

subcategory

string

For category water_barrier :

breakwater
groyne

Provides fine-grained classification based on the specific function of the structure to enable filtering depending on the use case.

z_level

integer

[-5, 5]

The integer value used to determine the drawing order of overlapping structure segments. The values are in the range -5, 5 inclusive.

overlays

Features in this layer represent areas of the earth's surface based on special status with a prescribed use/restrictions established by different entities.

Geometry type: `POLYGON`

overlays tags	Values	Description
group string	`protected` `military`	This tag specifies to which group a given feature belongs.
category string	For group `protected` : `national_park` `protected_area` `aboriginal`	This tag narrows down the group values allowing fine-grained styling and provides a distinction between areas in the same group.
primary_tag string	`lds:` `bdr:` `lsr:` `mlt:`	Fine-grain attribution of each feature corresponding to the most relevant value found among different primary tags (leisure, landuse, boundary, etc...) for more precise filtering or custom styling.
display_class integer	[1, 16]	A numerical value attribute that enables ordering and filtering based on the ranking of the area. The values are in the range 1, 16 inclusive.
protect_class integer	[1, 6]	A numerical value attribute that enables ordering and filtering based on the protection status of the area. The values are in the range 1, 6 inclusive.

built_up_areas

The built_up_areas layer contains features that represent urbanised area with large/dense concentration of buildings.

Geometry type: `POLYGON`

built_up_areas tags	Values	Description
category string	`built_up_area`	This tag specifies to which category a given feature belongs.

built_up_areas tags

Values

Description

category

string

built_up_area

This tag specifies to which category a given feature belongs.

transit

The transit layer contains line geometries that represent public and private transit network for person and goods. It conflates entities coming from different means of transportation.

Geometry type: `LINESTRING`

transit tags	Values	Description
category string	`railway` `ferry` `aerialway` `aeroway` `platform`	This tag specifies to which category a given feature belongs.
subcategory string	For category `railway` : `main` `subway` `tram` `light` `special` For category `aerialway` : `cabin` `lift` `goods` For category `aeroway` : `runway` `taxiway`	This tag narrows down the category values allowing fine-grained styling and provides a distinction between features in the same category.
z_level integer	[-5, 5]	The integer value used to determine the drawing order of overlapping transit segments. The values are in the range -5, 5 inclusive.
bridge boolean	`true`	This tag indicates that the feature is part of a bridge. The value is always true. If the feature is not a part of a bridge, then this tag is absent.
tunnel boolean	`true`	This tag indicates that the feature is part of a tunnel. The value is always true. If the feature is not a part of a tunnel, then this tag is absent.
service boolean	`true`	This tag indicates minor tracks present in proximity of railway stations and yards. The value is always true if applicable, otherwise absent.
under_construction boolean	`true`	This tag indicates that the feature is under construction. The value is always true. If the feature is not under construction, then this tag is absent.
toll boolean	`true`	This tag indicates that it is necessary to pay a toll to use a transit. The value is always true. If the transit is not paid, the this tag is absent.
modality string	`aerial` `rail` `tram` `bus` `subway` `ferry`	Attribution to qualify the main mobility type of a passenger transportation feature.
name string	-	A transit name in an NGT (Neutral Ground Truth) language; the native language of each country, respectively.
name_[language] string	-	A transit name in a language specified in a [language] suffix. List of supported languages.
reference_number string	-	This tag contains reference numbers or code for a route or transit segment.

transit_areas

The transit_areas layer contains public and private transit areas/facilities for person and goods. It conflates entities coming from different means of transportation.

Geometry type: `POLYGON`

transit_area tags	Values	Description
category string	`aeroway` `platform`	This tag specifies to which category a given feature belongs.
subcategory string	For category `aeroway` : `runway` `apron` `taxiway`	This tag narrows down the category values allowing fine-grained styling and provides a distinction between features in the same category.
z_level integer	[-5, 5]	The integer value used to determine the drawing order of overlapping transit areas. The values are in the range -5, 5 inclusive.

transit_area tags

Values

Description

category

string

aeroway

platform

This tag specifies to which category a given feature belongs.

subcategory

string

For category aeroway :

runway
apron
taxiway

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

z_level

integer

[-5, 5]

The integer value used to determine the drawing order of overlapping transit areas. The values are in the range -5, 5 inclusive.

water

The water layer contains area geometries that represent oceans, seas, lakes, and other water bodies.

Geometry type: `POLYGON`

water tags	Values	Description
category string	`water` `glacier`	This tag specifies to which category a given feature belongs.
intermittent boolean	`true`	Indicates whether the water body does not permanently contain water, including seasonal variation. Always true, absent if not applicable.
display_class integer	[1, 15]	A numerical value attribute that enables ordering and filtering based on the ranking of the area. The values are in the range 1, 15 inclusive.

water tags

Values

Description

category

string

water

glacier

This tag specifies to which category a given feature belongs.

intermittent

boolean

true

Indicates whether the water body does not permanently contain water, including seasonal variation. Always true, absent if not applicable.

display_class

integer

[1, 15]

A numerical value attribute that enables ordering and filtering based on the ranking of the area. The values are in the range 1, 15 inclusive.

buildings

This layer represents building footprints.

Geometry type: `POLYGON`

buildings tags	Values	Description
category string	`business` `shopping` `eat_and_drink` `public` `healthcare` `lodging` `religion` `education` `parking` `cultural` `leisure` `transport`	This tag specifies to which category a given feature belongs.
primary_tag string	`bdg:` `amn:` `off:` `arw:` `hst:` `trs:` `shp:` `ptr:`	Fine-grain attribution of each building feature corresponding to the most relevant value found among different feature tags for more precise filtering or custom styling.
underground boolean	`true`	Indicates that building is underground, such as subway station, parking, etc...
height float	-	Building height represents the height of the Building Footprint measured from the ground level to the top of the structure. When a Building Footprint has a ground height, building height represents the height of the actual structure. The height is represented in meters.
ground_height float	-	Ground height represents the height of the Building Footprint measured from the ground level to the bottom of the structure. The height is represented in meters.
part boolean	`true`	Indicates that building is part of bigger structure. Allow you to differentiate a building into parts that differ from each other in terms of some building attributes or the building function.

water_lines

The water_lines layer contains line geometries that represent river and stream center lines.

Geometry type: `LINESTRING`

water_lines tags	Values	Description
category string	`river` `stream` `canal` `drain` `ditch`	This tag specifies to which category a given feature belongs.
artificial boolean	`true`	Indicates whether the water body is man-made or natural. Always true, absent if not applicable.
intermittent boolean	`true`	Indicates whether the water body does not permanently contain water, including seasonal variation. Always true, absent if not applicable.
tunnel boolean	`true`	This tag indicates that the water body is part of a tunnel. The value is always true. If the water body is not a part of a tunnel, then this tag is absent.
bridge boolean	`true`	This tag indicates that the water body is part of a bridge. The value is always true. If the water body is not a part of a bridge, then this tag is absent.
name string	-	A feature name in a NGT (Neutral Ground Truth) language.
name_[language] string	-	A feature name in a language specified in a [language] suffix. List of supported languages.

places

This layer contains points for labeling places including countries, states, cities, and towns.

Geometry type: `POINT`

places tags	Values	Description
category string	`country` `admin_division` `settlement` `settlement_division`	This tag specifies to which category a given feature belongs.
subcategory string	For category `admin_division` : `state` For category `settlement` : `city` `town` `village` `hamlet` For category `settlement_division` : `borough` `suburb` `quarter` `neighbourhood`	This tag narrows down the category values allowing fine-grained styling and provides a distinction between places in the same category.
name string	-	A feature name in an NGT (Neutral Ground Truth) language; the native language of each country, respectively.
name_[language] string	-	A feature name in a language specified in a [language] suffix. List of supported languages.
admin_class integer	[2, 11]	Indicates if a settlement is the capital of an administrative area of a given level (2=country, 4=state, etc.). The values are in the range 2, 11 inclusive.
display_class integer	[1, 12]	Represents a classification of places based on their importance with respect to map display. The values are in the range 1, 12 inclusive.
icon string	`capital` `city_large` `city_medium` `city_small` `town`	The identifier of the icon asset in the TomTom styles that should be used for the visualization purpose of the Point of Interest.
id string	-	A unique place identifier that can be used across other TomTom services.
country_code string	-	ISO-3166 code of the country for a given label point.
state_code string	-	ISO-3166 code of state or first sub-national subdivision for label points.

poi

The POI layer represents points of interest.

Geometry type: `POINT`

poi tags	Values	Description
group string	`business` `cultural` `driving` `eat_and_drink` `education` `finance` `healthcare` `leisure` `lodging` `military` `outdoor` `parking` `protected` `public` `religion` `shopping` `sport` `transport`	This tag provides a broad grouping of the Points of Interest entities based on general semantic affiliations.
category string	For group `business` : `commercial_area` `conference_center` `industrial_area` For group `cultural` : `cultural_center` `historic_site` `landmark` `museum` `theater` For group `driving` : `border_control` `charging_location` `fuel_station` `mountain_pass` `rest_and_service_area` `toll_booth` `truck_stop` `vehicle_repair` `vehicle_wash` `weighbridge` For group `eat_and_drink` : `bar` `cafe` `coffee_shop` `fast_food` `food_court` `pub` `restaurant` For group `education` : `childcare` `college_or_university` `school_or_kindergarten` For group `finance` : `atm` `bank` For group `leisure` : `amusement_park` `beach_resort` `cinema` `ice_rink` `nightlife` `stadium` `tourist_attraction` `zoo_or_aquarium` For group `lodging` : `camping_ground` `hotel_or_motel` For group `healthcare` : `clinic` `dentist` `doctor` `emergency_ward_entrance` `hospital` `pharmacy` For group `military` : `military_airfield` `military_facility` For group `outdoor` : `park_and_recreation_area` `park_and_recreation_facility` `viewpoint` For group `parking` : `bicycle_parking` `motorcycle_parking` `parking_facility` `rental_car_parking` For group `protected` : `aboriginal_land` `national_park` `protected_land` For group `public` : `courthouse` `fire_station` `government_office` `police_station` `post_office` `prison` `public_library` `townhall` `vehicle_inspection` For group `religion` : `cemetery` `religious_site` For group `shopping` : `animal_service` `bicycle_rental` `car_rental` `clothing_shop` `consumer_service` `department_store` `food_and_drinks_shop` `mall` `marketplace` `motorcycle_rental` `personal_care_service` `retail_area` `shop_or_store` `supermarket` `vehicle_dealer` `veterinary` For group `sport` : `fitness_center` `golf_course` `sport_facility` `winter_sports` For group `transport` : `aerialway_station` `airport` `bus_station` `car_sharing` `ferry_terminal` `heliport_or_helipad` `public_transport_platform` `public_transport_station` `public_transport_stop` `railway_station` `taxi_stand` `transport_access`	This tag groups Points of Interest into broad categories that can be used for styling purposes.
primary_tag string	`arl:` `arw:` `amn:` `brr:` `bnd:` `clb:` `crf:` `emr:` `hgw:` `hst:` `lds:` `lsr:` `mnm:` `mlt:` `mnt:` `off:` `ptr:` `rlw:` `shp:` `trs:`	Fine-grain attribution of each POI feature corresponding to the most relevant value found among different feature tags for more precise filtering or custom styling.
display_class integer	[1, 18]	A numerical value attribute that enables ordering and filtering based on the importance/relevance of the POI. The values are in the range 1, 18 inclusive.
priority integer	-	The tag value represents an absolute priority of the POI among all the POI features.
profile string	`car` `truck` `motorcycle` `bicycle` `passenger`	The tag value represents a use profile for which the POI entity is relevant.
modality string	`car` `taxi` `bus` `rail` `tram` `subway` `aerial` `ferry`	Attribution to qualify the main mobility type of a passenger transportation feature.
name string	-	A POI name in an NGT (Neutral Ground Truth) language; the native language of each country, respectively.
name_[language] string	-	A POI name in a language specified in a [language] suffix. List of supported languages.
sub_text string	-	Attribute that captures additional information about POIs, depending on their group affiliation.
brand string	-	Attribute that captures POI brand information.
id string	-	A unique POI identifier that can be used across other services.
semantic_id string	-	Semantic id associated to each feature `primary_tag`.

carto_labels

The carto_labels layer includes points that represent cartographic labels.

Geometry type: `POINT`

carto_labels tags	Values	Description
category string	`island` `water` `glacier` `woodland` `sandy` `natural_feature` `elevation_point` `grassland`	This tag specifies to which category a given feature belongs.
subcategory string	For category `island` : `archipelago` `island` `islet` For category `water` : `ocean` `sea` `bay` `strait` `inland` For category `grassland` : `natural` `managed` For category `sandy` : `sand` `beach` For category `natural_feature` : `plain` `plateau` `valley` `cape` `isthmus` For category `elevation_point` : `peak` `volcano` `hill` `saddle`	This tag narrows down the category values allowing fine-grained styling and provides a distinction between places in the same category.
intermittent boolean	`true`	Indicates whether the water body does not permanently contain water, including seasonal variation. Always true, absent if not applicable.
display_class integer	[0, 13]	A numerical value attribute that enables ordering and filtering based on the size of the corresponding feature or other ranking method. The values are in the range 0, 13 inclusive.
name string	-	A feature name in an NGT (Neutral Ground Truth) language; the native language of each country, respectively.
name_[language] string	-	A feature name in a language specified in a [language] suffix. List of supported languages.
elevation integer	[1, 8850]	A numeric value attribute representing the elevation of the point in meters above the sea level.

roads

The roads layers include lines that can be used for drawing roads.

Geometry type: `LINESTRING`

roads tags	Values	Description
category string	`motorway` `motorway_link` `trunk` `trunk_link` `primary` `primary_link` `secondary` `secondary_link` `tertiary` `tertiary_link` `street` `service` `bus` `pedestrian` `track` `path`	This tag specifies to which category a given feature belongs.
subcategory string	For category `street` : `unclassified` `residential` `living_street` For category `service` : `parking` `alley` `driveway` `emergency` For category `path` : `footway` `steps` `bridleway` `cycleway`	This tag narrows down the category values allowing fine-grained styling and provides a distinction between places in the same category.
direction integer	`1` `-1`	This tag indicates that traffic on a road is one-way. Value 1 indicates that the traffic flows in the same direction as geometry of the road, and the value -1 indicates that the traffic flows in the opposite direction to the geometry of the road.
bridge boolean	`true`	This tag indicates that the road is part of a bridge. The value is always true. If the road is not a part of a bridge, then this tag is absent.
tunnel boolean	`true`	This tag indicates that the road is part of a tunnel. The value is always true. If the road is not a part of a tunnel, then this tag is absent.
covered boolean	`true`	Indicates that the road is covered but open at least on one side. The value is always true, If road is not covered or fully covered this tag is absent.
z_level integer	[-5, 5]	The integer value used to determine the drawing order of overlapping road segments. The values are in the range -5, 5 inclusive.
under_construction boolean	`true`	This tag indicates that the road is under construction. The value is always true. If the road is not under construction, then this tag is absent.
display_class integer	[5, 15]	A numerical value attribute that enables ordering and filtering based on the ranking of the road. The values are in the range 5, 15 inclusive.
unpaved boolean	`true`	This tag indicates that the road surface is not paved. The value is always true. If the road is paved then this tag is absent.
toll boolean	`true`	This tag indicates that it is necessary to pay a toll to use a road. The value is always true. If the road is not paid, then this tag is absent.
grade integer	[-6, 6]	Depending on the road type, indicates the degree of difficulty to be expected by the user (depending on either the steepness, level of maintenance, etc). The values are in the range -6, 6 inclusive.
access string	`prohibited` `restricted` `conditional`	Indicates if the road is access-restricted to the general public, to some specific use or category or based on certain conditions (e.g. time, day)
name string	-	A road name in an NGT (Neutral Ground Truth) language; the native language of each country, respectively.
name_[language] string	-	A road name in a language specified in a [language] suffix. List of supported languages.
route_number string	-	Text to be placed on the road shield icon.
route_shield_text string	-	Primary route shield text for a given road to be used as the label of the road shield symbol.
route_shield_text[x][1..3] string	-	Alternate route shield(s) text for a given road to be used as the label of the road shield symbol.
route_shield_id integer	-	Primary route shield id for a given road to reference a unique route type id.
route_shield_id[x][1..3] integer	-	Alternate route shield(s) id for a given road to reference a unique route type id.
route_shield_icon string	-	Primary route shield icon name for a given road to be used to source the asset of the road shield symbol.
route_shield_icon[x][1...3] string	-	Alternate route shield(s) icon name for a given road to be used to source the asset of the road shield symbol.
route_shield_text_color string	-	Primary route shield text color for a given road to style the text in the road shield symbol.
route_shield_text_color_[x] [1...3 string	-	Alternate route shield(s) text color for a given road to style the text in the road shield symbol.

roads_areas

The roads_areas layers include polygons that can be used for drawing road areas.

Geometry type: `POLYGON`

roads_area tags	Values	Description
category string	`pedestrian` `service` `path`	This tag specifies to which category a given feature belongs.
bridge boolean	`true`	This tag indicates that the road area is part of a bridge. The value is always true. If the road area is not a part of a bridge, then this tag is absent.
tunnel boolean	`true`	This tag indicates that the road area is part of a tunnel. The value is always true. If the road area is not a part of a tunnel, then this tag is absent.
covered boolean	`true`	Indicates that the road area is covered but open at least on one side. The value is always true, If road area is not covered or fully covered this tag is absent.
z_level integer	[-5, 5]	The integer value used to determine the drawing order of overlapping road areas. The values are in the range -5, 5 inclusive.
display_class integer	[5, 15]	A numerical value attribute that enables ordering and filtering based on the ranking of the road. The values are in the range 5, 15 inclusive.
unpaved boolean	`true`	This tag indicates that the road surface is not paved. The value is always true. If the road is paved then this tag is absent.
access string	`prohibited` `restricted` `conditional`	Indicates if the road is access-restricted to the general public, to some specific use or category or based on certain conditions (e.g. time, day)

roads_points

Features in this layer represent man-made structures.

Features in this layer represent points related to the road network, including road furniture (traffic lights and signs), junction/exit points, special traffic figures (mini roundabouts, turning loops, etc...) and other relevant features.

Geometry type: `POLYGON`

roads_points tags	Values	Description
category string	`highway_exit` `turning_feature`	Provides macro-classification based on the main type of road-related point.
subcategory string	For category `turning_feature` : `mini_roundabout` `turning_loop` `turning_circle`	Provides fine-grained classification based on the original definition of the feature to enable filtering depending on the use case.
number string	-	The highway exit reference number to be visualized on the point.
name string	-	The highway exit name to be visualized on the point on higher zoom levels if needed.
destination string	-	The main destination name of the highway exit to be visualized on the point on higher zoom levels if needed.

boundaries

The boundaries layer includes boundary lines for national and subnational administrative units.

Geometry type: `LINESTRING`

boundaries tags	Values	Description
category string	`country` `state`	This tag specifies to which category a given feature belongs.
treaty boolean	`true`	This tag indicates that the border is the result of an agreement under international law entered by sovereign states and international organizations but is still experienced as a very sensitive geopolitical matter.
disputed boolean	`true`	This tag indicates that the border is the subject of a dispute between two or more countries. It does not give information about the nature of the dispute.
name string	-	A feature name in an NGT (Neutral Ground Truth) language; the native language of each country, respectively.
name_[language] string	-	A feature name in a language specified in a [language] suffix. List of supported languages.

Handling label translations

Vector tiles contain all available translations for suitable layers and features, i.e., POINT features in the places layer. These translations can be used in style files to change the label language. In order to use translations, you need to modify the desired layer in the style file by replacing the value of the text-field key with the following expression:

["coalesce",["get", "name_[language]"],["get", "name"]]

The [language] part in name_[language] needs to be replaced by one of the supported languages.

Example:

1{
  ...
  "id": "Places - Capital",
  "layout": {
      "text-anchor": "center",
      "text-field": ["coalesce",["get", "name_en-GB"],["get", "name_en"],["get", "name"]],
      "text-font": ["Noto-Bold"],
      "text-justify": "auto",
      "text-letter-spacing": 0.05,
      ...
  }
  ...
13}

To combine the translated label with other tags the following expression can be used:

["concat",["coalesce",["get", "name_[language]"],["get", "name"]], ["get", "[tag_name]"]]

The [language] part in name_[language] needs to be replaced by one of the supported languages.
The [tag_name] should be replaced by one of the tags available in the version 2 tile.

Example:

1{
  ...
  "id": "POI",
  "layout": {
      "text-anchor": "center",
      "text-field": ["concat",["coalesce",["get', "name_en-GB"],["coalesce",["get', "name_en"],["get", "name"]], "\n", ["get", "sub_text"]],
      "text-font": ["Noto-Bold"],
      "text-justify": "auto",
      "text-letter-spacing": 0.05,
      ...
  }
  ...
13}

Content

Important notes:

TomTom Vector Format

Legend

TomTom Vector Schema

Schema data

Decoding tile geometry

Command

Count

Coordinates

Examples

For a POINT type feature:

Input:

Decoding:

Output:

For a LINESTRING type feature:

Input:

Decoding:

Output:

For a POLYGON type feature:

Input:

Decoding:

Output:

Decoding feature tags

Example

Tile Layers

earth_cover

Geometry type: POLYGON

land_cover

Geometry type: POLYGON

land_use

Geometry type: POLYGON

structures

Geometry type: POLYGON

structures_lines

Geometry type: LINESTRING

overlays

Geometry type: POLYGON

built_up_areas

Geometry type: POLYGON

transit

Geometry type: LINESTRING

transit_areas

Geometry type: POLYGON

water

Geometry type: POLYGON

buildings

Geometry type: POLYGON

water_lines

Geometry type: LINESTRING

places

Geometry type: POINT

poi

Geometry type: POINT

carto_labels

Geometry type: POINT

roads

Geometry type: LINESTRING

roads_areas

Geometry type: POLYGON

roads_points

Geometry type: POLYGON

boundaries

Geometry type: LINESTRING

Handling label translations

For a `POINT` type feature:

For a `LINESTRING` type feature:

For a `POLYGON` type feature:

Geometry type: `POLYGON`

Geometry type: `POLYGON`

Geometry type: `POLYGON`

Geometry type: `POLYGON`

Geometry type: `LINESTRING`

Geometry type: `POLYGON`

Geometry type: `POLYGON`

Geometry type: `LINESTRING`

Geometry type: `POLYGON`

Geometry type: `POLYGON`

Geometry type: `POLYGON`

Geometry type: `LINESTRING`

Geometry type: `POINT`

Geometry type: `POINT`

Geometry type: `POINT`

Geometry type: `LINESTRING`

Geometry type: `POLYGON`

Geometry type: `POLYGON`

Geometry type: `LINESTRING`