Content

Service version: 2
Last edit: 2024.09.19

Public Preview Notice

This API is in Public Preview. Go to the Public Preview - what is it? page to see what this means.

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.

Vector tile property dependencies

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
7 enum GeomType {
8 UNKNOWN = 0;
9 POINT = 1;
10 LINESTRING = 2;
11 POLYGON = 3;
12 }
13
14 message Value {
15 optional string string_value = 1;
16 optional float float_value = 2;
17 optional double double_value = 3;
18 optional int64 int_value = 4;
19 optional uint64 uint_value = 5;
20 optional sint64 sint_value = 6;
21 optional bool bool_value = 7;
22 extensions 8 to max;
23 }
24
25 message Feature {
26 optional uint64 id = 1 [ default = 0 ];
27 repeated uint32 tags = 2 [ packed = true ];
28 optional GeomType type = 3 [ default = UNKNOWN ];
29 repeated uint32 geometry = 4 [ packed = true ];
30 optional bytes raster = 5;
31 }
32
33 message Layer {
34 required uint32 version = 15 [ default = 1 ];
35 required string name = 1;
36 repeated Feature features = 2;
37 repeated string keys = 3;
38 repeated Value values = 4;
39 optional uint32 extent = 5 [ default = 4096 ];
40
41 extensions 16 to max;
42 }
43
44 repeated Layer layers = 3;
45
46 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.

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
2 feature: 0
3 type: POINT
4 geometry: [9, 1136, 6564]

Decoding:

1geometry:
2 command_and_count = 9
3 command = 9 & 0x7 = 1
4 count = 9 >> 0x3 = 1
5
6 x= 1136, y0 = 6564
7 decode(x0) = ((1136 >> 0x1) ^ (-(1136 & 0x1))) = 568
8 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
2 feature: 0
3 type: LINESTRING
4 geometry: [9, 846, 2312, 10, 652, 1938]

Decoding:

1geometry:
2 1:
3 command_and_count = 9
4 command = 9 & 0x7 = 1
5 count = 9 >> 0x3 = 1
6
7 x0' = 846, y0' = 2312
8 decode(x0') = ((846 >> 0x1) ^ (-(846 & 0x1))) = 423
9 decode(y0') = ((2312 >> 0x1) ^ (-(2312 & 0x1))) = 1156
10 2:
11 command_and_count = 10
12 command = 10 & 0x7 = 2
13 count = 10 >> 0x3 = 1
14
15 x0 = 652, y0 = 1938
16 decode(x0) = decode(x0') + ((x0 >> 0x1) ^ (-(x0 & 0x1)))
17 decode(y0) = decode(y0') + ((y0 >> 0x1) ^ (-(y0 & 0x1)))
18 decode(x0) = 423 + ((652 >> 0x1) ^ (-(652 & 0x1))) = 749
19 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
2 feature: 0
3 type: POLYGON
4 geometry: [9, 1320, 5622, 26, 416, 707, 68, 612, 483, 96, 7]

Decoding:

1geometry:
2 1:
3 command_and_count = 9
4 command = 9 & 0x7 = 1
5 count = 9 >> 0x3 = 1
6
7 x0' = 1320, y0' = 5622
8 decode(x0') = ((1320 >> 0x1) ^ (-(1320 & 0x1))) = 660
9 decode(y0') = ((5622 >> 0x1) ^ (-(5622 & 0x1))) = 2811
10 2:
11 command_and_count = 26
12 command = 26 & 0x7 = 2
13 count = 26 >> 0x3 = 3
14
15 x0 = 1736, y0 = 4914
16 decode(x0) = decode(x0') + ((416 >> 0x1) ^ (-(416 & 0x1))) = 660 + 208 = 868
17 decode(y0) = decode(y0') + ((707 >> 0x1) ^ (-(707 & 0x1))) = 2811 + (-354) = 2457
18
19 x1 = 68, y1 = 612
20 decode(x1) = decode(x0) + ((68 >> 0x1) ^ (-(68 & 0x1))) = 902
21 decode(y1) = decode(y0) + ((612 >> 0x1) ^ (-(612 & 0x1))) = 2763
22
23 x2 = 483, y2 = 96
24 decode(x2) = decode(x1) + ((483 >> 0x1) ^ (-(483 & 0x1))) = 660
25 decode(y2) = decode(y1) + ((96 >> 0x1) ^ (-(96 & 0x1))) = 2811
26 3:
27 command_and_count = 7
28 command = 7 & 0x7 = 7
29 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
2 keys: ["country_code", "icon_text"],
3 values: ["SWE", "E4"]
4 feature: 0
5 tags : [0,0,1,1]

After decoding it has to be read like this:

1layer: 0
2 feature: 0
3 properties:
4 country_code : "SWE"
5 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.

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

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

permanent_water


intermittent_water

This tag specifies to which category a given feature belongs.

buildings

This layer represents building footprints.

Geometry type: POLYGON

buildings tags

Values

Description

category


string

cultural


industrial


government


hospital


hotel


place_of_worship


railway_station


subway_station


education


This tag specifies to which category a given feature belongs.

subcategory


string

For category education :

  • school

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

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.

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

permanent_water

This tag specifies to which category a given feature belongs.

subcategory


string

For category permanent_water :

  • river

This tag narrows down the category values allowing fine-grained styling and provides a distinction between places in the same category. Please note that the river subcategory is also present in the carto_labels layer. The river feature from water_lines layer represents a river of line-type geometry with its data.

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


state


settlement


settlement_division


address_point

This tag specifies to which category a given feature belongs.

subcategory


string

For category settlement :

  • city

  • town

  • village

  • hamlet

For category settlement_division :

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

abbr


string

-

This tag provides an abbreviation of the state name. It will only be present for features with category state.

capital


string

country


state

This tag value indicates the administrative importance of point.

priority


integer

-

The tag value represents a priority of the city which is based on the combination of the population of the city and its administrative importance. The lower the value of this tag the more important the city is.

admin_class


integer

-

The tag value represents the administrative importance of a place.

display_class


integer

-

The tag value represents a classification of places based on their importance with respect to map display.

icon


string

-

The identifier of the icon asset in the TomTom styles that should be used for the visualization purpose of the Point of Interest.

id


integer

-

A unique place identifier that can be used across other TomTom services.

number


string

-

Address point (house) number. Available only when the category is address_point.

poi_basic

The POI layers represent points of interest. The difference between the poi_basic and the poi_extended layer is the amount of available categories.

Geometry type: POINT

poi_basic tags

Values

Description

category


string

industrial_building


college_or_university


fire_station_or_brigade


government_office


library


military_installation


native_reservation


police_station


post_office


prison_or_correctional_facility


school


hospital


amusement_park


museum


park_and_recreation_area


zoo_arboreta_and_botanical_garden


shopping_center


golf_course


stadium


tourist_attraction


place_of_worship


airport


ferry_terminal


public_transportation_stop


railroad_station


geographic_feature

This tag groups Points of Interest into broad categories that can be used for styling purposes.

subcategory


string

For category park_and_recreation_area :

  • national_park

  • cemetery

For category place_of_worship :

  • church

  • mosque

  • synagogue

  • temple

  • gurudwara

  • ashram

  • pagoda

For category public_transportation_stop :

  • bus_stop

  • taxi_stand

  • coach_stop

  • streetcar_stop

For category railroad_station :

  • international_railroad_station

  • national_railroad_station

  • subway_station

For category geographic_feature :

  • mountain_peak

  • ridge

  • valley

  • reef

  • hill

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.

id


string

-

A unique Point of Interest identifier that can be used across other TomTom services.

category_id


integer

-

An identifier representing a category. Either a 4 digits integer for Points of Interest without subcategory or a 7 digits integer for Points of Interest with subcategory (where the first 4 digits identify a category). It can be used across other TomTom services.

priority


integer

-

The tag value represents a priority of the Point of Interest. The lower the value of this tag the more important the Point of Interest is.

icon


integer

-

The identifier of the icon asset in the TomTom styles that should be used for the visualization purpose of the Point of Interest.

sub_text


string

-

The additional information about POIs, i.e., if available, for a hill it contains its height in meters, in the countries where imperial units are used the height is in feet.

The Category ID and Subcategory ID in the following table correspond to the ID in poiCategories in the Search API.

Category

Category ID

Possible subcategories

Subcategory ID

industrial_building9383--
college_or_university7377--
fire_station_or_brigade7392--
government_office7367--
library9913--
military_installation9388--
native_reservation9389--
police_station7322--
post_office7324--
prison_or_correctional_facility9154--
school7372--
hospital7321--
amusement_park9902--
museum7317--
park_and_recreation_area9362

national_park


cemetery

9362008


9362003

zoo_arboreta_and_botanical_garden9927--
shopping_center7373--
golf_course9911--
stadium7374--
tourist_attraction7376--
place_of_worship7339

church


mosque


synagogue


temple


gurudwara


ashram


pagoda

7339002


7339003


7339004


7339005


7339006


7339007


7339008

airport7383--
ferry_terminal7352--
public_transportation_stop9942

bus_stop


taxi_stand


coach_stop


streetcar_stop

9942002


9942003


9942005


9942004

railroad_station7380

international_railroad_station


national_railroad_station


subway_station

738002


738003


738005

geographic_feature8099

mountain_peak


ridge


valley


reef


hill

8099002


8099004


8099006


8099014


8099025

poi_extended

The POI layers represent points of interest. The difference between the poi_basic and the poi_extended layer is the amount of available categories.

Geometry type: POINT

poi_extended tags

Values

Description

category


string

automotive_dealer


car_wash


electric_vehicle_station


motoring_organization_office


open_parking_area


parking_garage


gas_station


rent_a_car_facility


rent_a_car_parking


repair_facility


rest_area


toll_gate


truck_stop


weigh_station


agriculture_business


bank


business_park


atm


commercial_building


company


courier_drop_box


emergency_medical_service


exchange


exhibition_and_convention_center


industrial_building


manufacturing_facility


media_facility


research_facility


cafe_or_pub


restaurant


restaurant_area


college_or_university


courthouse


embassy


fire_station_or_brigade


government_office


library


military_installation


native_reservation


non_governmental_organization


police_station


post_office


primary_resource_or_utility


prison_or_correctional_facility


public_amenity


school


traffic_service_center


transport_authority_or_vehicle_registration


welfare_organization


dentist


doctor


emergency_room


health_care_service


hospital


pharmacy


veterinarian


amusement_park


casino


movie_theater


club_and_association


community_center


cultural_center


entertainment


leisure_center


marina


museum


nightlife


park_and_recreation_area


theater


trail_system


winery


zoo_arboreta_and_botanical_garden


camping_ground


vacation_rental


hotel_or_motel


residential_accommodations


department_store


market


shop


shopping_center


golf_course


ice_skating_rink


sports_center


stadium


swimming_pool


tennis_court


water_sport


adventure_sports_venue


beach


tourist_attraction


place_of_worship


scenic_or_panoramic_view


tourist_information_office


access_gateway


airport


checkpoint


ferry_terminal


frontier_crossing


helipad


mountain_pass


port_or_warehouse_facility


public_transportation_stop


railroad_station


geographic_feature

This tag groups Points of Interest into broad categories that can be used for styling purposes.

subcategory


string

For category cafe_or_pub :

  • cafe

  • pub

  • internet_cafe

  • tea_house

  • coffee_shop

  • microbrewery

For category park_and_recreation_area :

  • national_park

  • cemetery

For category place_of_worship :

  • church

  • mosque

  • synagogue

  • temple

  • gurudwara

  • ashram

  • pagoda

For category public_transportation_stop :

  • bus_stop

  • taxi_stand

  • coach_stop

  • streetcar_stop

For category railroad_station :

  • international_railroad_station

  • national_railroad_station

  • subway_station

For category geographic_feature :

  • mountain_peak

  • cave

  • ridge

  • dune

  • valley

  • plain_or_flat

  • plateau

  • pan

  • well

  • oasis

  • rocks

  • reservoir

  • reef

  • rapids

  • bay

  • cove

  • harbor

  • lagoon

  • cape

  • mineral_or_hot_springs

  • island

  • marsh

  • river_crossing

  • hill

  • quarry

  • locale

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.

id


string

-

A unique Point of Interest identifier that can be used across other TomTom services.

category_id


integer

-

An identifier representing category. Either 4 digits integer for Points of Interest without subcategory or 7 digits integer for Points of Interest with subcategory (where the first 4 digits identify a category). It can be used across other TomTom services.

priority


integer

-

The tag value represents a priority of the Point of Interest. The lower the value of this tag the more important the Point of Interest is.

icon


integer

-

The identifier of the icon asset in the TomTom styles that should be used for the visualization purpose of the Point of Interest.

The Category ID and Subcategory ID in the following table correspond to the ID in poiCategories in the Search API.

Category

Category ID

Possible subcategories

Subcategory ID

automotive_dealer9910--
car_wash9155--
electric_vehicle_station7309--
motoring_organization_office7368--
open_parking_area7369--
parking_garage7313--
gas_station7311--
rent_a_car_facility7312--
rent_a_car_parking9930--
repair_facility7310--
rest_area7395--
toll_gate7375--
truck_stop7358--
weigh_station7359--
agriculture_business7335--
bank7328--
business_park7378--
atm7397--
commercial_building9382--
company9352--
courier_drop_box7388--
emergency_medical_service7391--
exchange9160--
exhibition_and_convention_center9377--
industrial_building9383--
manufacturing_facility9156--
media_facility9158--
research_facility9157--
cafe_or_pub9376

cafe


pub


internet_cafe


tea_house


coffee_shop


microbrewery

9376002


9376003


9376004


9376005


9376006


9376007

restaurant7315--
restaurant_area9359--
college_or_university7377--
courthouse9363--
embassy7365--
fire_station_or_brigade7392--
government_office7367--
library9913--
military_installation9388--
native_reservation9389--
non_governmental_organization9152--
police_station7322--
post_office7324--
primary_resource_or_utility9150--
prison_or_correctional_facility9154--
public_amenity9932--
school7372--
traffic_service_center7301--
transport_authority_or_vehicle_registration9151--
welfare_organization9153--
dentist9374--
doctor9373--
emergency_room9956--
health_care_service9663--
hospital7321--
pharmacy7326--
veterinarian9375--
amusement_park9902--
casino7341--
movie_theater7342--
club_and_association9937--
community_center7363--
cultural_center7319--
entertainment9900--
leisure_center9378--
marina7347--
museum7317--
nightlife9379--
park_and_recreation_area9362

national_park


cemetery

9362008


9362003

theater7318--
trail_system7302--
winery7349--
zoo_arboreta_and_botanical_garden9927--
camping_ground7360--
vacation_rental7304--
hotel_or_motel7314--
residential_accommodations7303--
department_store7327--
market7332--
shop9361--
shopping_center7373--
golf_course9911--
ice_skating_rink9360--
sports_center7320--
stadium7374--
swimming_pool7338--
tennis_court9369--
water_sport9371--
adventure_sports_venue7305--
beach9357--
tourist_attraction7376--
place_of_worship7339

church


mosque


synagogue


temple


gurudwara


ashram


pagoda

7339002


7339003


7339004


7339005


7339006


7339007


7339008

scenic_or_panoramic_view7337--
tourist_information_office7316--
access_gateway7389--
airport7383--
checkpoint9955--
ferry_terminal7352--
frontier_crossing7366--
helipad7308--
mountain_pass9935--
port_or_warehouse_facility9159--
public_transportation_stop9942

bus_stop


taxi_stand


coach_stop


streetcar_stop

9942002


9942003


9942005


9942004

railroad_station7380

international_railroad_station


national_railroad_station


subway_station

738002


738003


738005

geographic_feature8099

mountain_peak


cave


ridge


dune


valley


plain_or_flat


plateau


pan


well


oasis


rocks


reservoir


reef


rapids


bay


cove


harbor


lagoon


cape


mineral_or_hot_springs


island


marsh


river_crossing


hill


quarry


locale

8099002


8099003


8099004


8099005


8099006


8099007


8099008


8099009


8099010


8099011


8099012


8099013


8099014


8099015


8099016


8099017


8099018


8099019


8099020


8099021


8099022


8099023


8099024


8099025


8099026


8099027

carto_labels

The carto_labels layer includes points that represent cartographic labels. It also includes lines for some features like river that can be used to place a label along the geometry of the river.

Geometry type: POINT , LINESTRING

carto_labels tags

Values

Description

category


string

permanent_water : POINT


intermittent_water : POINT


woodland : POINT


island : POINT

This tag specifies to which category a given feature belongs.

subcategory


string

For category permanent_water :

  • ocean : POINT

  • sea : POINT

  • river : LINESTRING

  • lake : POINT

This tag narrows down the category values allowing fine-grained styling and provides a distinction between places in the same category. Please note that the river subcategory is also present in the water_lines layer. The river feature from the carto_labels layer represents a water center line of river of polygon- type geometry with its data.

id


string

-

A unique Point of Interest identifier that can be used across other TomTom services.

icon


string

-

The identifier of the icon asset in the TomTom styles that should be used for the visualization purpose of the Point of Interest.

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.

roads

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

Geometry type: LINESTRING

roads tags

Values

Description

category


string

motorway


trunk


primary


secondary


tertiary


street


minor


path


ferry


railway

This tag specifies to which category a given feature belongs.

subcategory


string

For category tertiary :

  • connecting

  • major_local

For category street :

  • local

  • minor_local

For category minor :

  • parking

  • pedestrian

  • restricted

  • service

For category path :

  • walkway

For category ferry :

  • rail

  • boat

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

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.

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, the this tag is absent.

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.

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.

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.

shield_icon_[0-4]


string

-

The name of the road shield icon associated with the road. For easier referencing and implementation, the name of a roadshield follows one of two formats:

  • shapeType-fillColor-strokeColor-numOfChars: For shields to be reused by many countries.

  • countryName-stateCode-shieldType-numOfChars: For country or region specific shields.


See the Shield icon shape types section for existing shape types.


See the Shield icon fill and stroke colors section for existing shield colors.


See the Shield icon countries and states section for details on country names and state codes.


numOfChars is a number in the range 1-7.


shieldType is a unique shield ID.

shield_icon_text_[0-4]


string

-

Text to be placed on the road shield icon with the corresponding shield_icon idx.

shield_icon_text_color_[0-4]


string

-

The color of the text on the road shield icon with the corresponding shield_icon idx. Should be used in day mode.

shield_icon_text_color_night_[0-4]


string

-

The color of the text on the road shield icon with the corresponding shield_icon idx. Should be used in night mode.

z_level


integer

-

The integer value used to determine the drawing order of overlapping road segments. The values are in the range -3, 3 inclusive. Note: This tag is currently sent from zoom level 13 inclusive up to zoom level 22.

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.

<restriction>


string

-

Value of restriction. The unit of this value is provided in the tag <restriction>_unit.
See: List of restrictions.

<restriction>_unit


integer

-

Unit of restriction value. Value is provided in the tag <restriction>.


See:


List of units.


List of restrictions.

<restriction>_icon


string

-

Road sign restriction icon.
See: List of restrictions.

<restriction>_priority


integer

-

Priority of restriction road sign.
See: List of restrictions.

<restriction>_period


string

-

Validity period in human-readable form. If the restriction starts or ends in the nearest 24 hours, then the tag contains a string with restriction validity hours. It contains a period in 12h or 24h format.
Examples:
"08:00-14:00"
"08:00am-02:00pm"

<restriction>_max_weight


float

-

Max weight.


List of restrictions.

allow_category


integer

1 - not allowed.


2 - not currently allowed (time restriction, e.g., not allowed now, but allowed in 1h).


3 - currently allowed (due to time restriction).

Tag indicates the status of restriction.

restriction_direction


integer

1
-1

The aggregated value of a restriction's direction. This tag indicates that all restrictions on the road are one-way. Value 1 indicates that all restrictions flow in the same direction as the geometry of the road, and the value -1 indicates that all restrictions flow in the opposite direction to the geometry of the road.

left_hand_traffic


boolean

  • true

This tag indicates that traffic is on the left side of the road. This tag is present only together with tag restriction_direction. The value is always true. If the road has the tag restriction_direction and traffic is on the right side, then this tag is absent.

Shield icon shape types

rectanglehexagonhexagon2octagonspecial01special02special03special04
shield01shield02shield03shield04shield05shield06shield07shield08
shield09shield10shield11shield12pentagoncirclepillus1
us2us3ovaldiamond

Shield icon fill and stroke colors

whiteyellow1yellow2yellow3orangegreen1green2green3blue1
blue2blue3brown1brown2redgreyanthraciteblack

Shield icon countries and states

Possible values of the countryName part of a name are listed in the following table.

  • For Canada shields, the stateCode part of the shield's name is either a two-letter province name abbreviation or empty.
  • For USA shields, the stateCode may be a two-letter ISO-3166 state name abbreviation, highway, county, or empty.
  • For other country shields the stateCode is empty.
colombiasouthmexicoindonesiataiwancanadausavenezuelasouthafrica
cubaindiaaustraliaargentinasaudiarabiauaeperukorea

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.

List of supported languages

Language name

Language tag

Neutral Ground Truth (custom)

ngt


Official languages for all regions in local scripts if available.

Neutral Ground Truth - Latin exonyms (custom)

ngt-Latn


Latin script will be used if available.

Arabic

ar

Bulgarian

bg-BG

Chinese (Taiwan)

zh-TW

Chinese (Simplified)

zh-CN

Czech

cs-CZ

Danish

da-DK

Dutch

nl-NL

English (Australia)

en-AU

English (Canada)

en-CA

English (Great Britain)

en-GB

English (New Zealand)

en-NZ

English (USA)

en-US

Finnish

fi-FI

French

fr-FR

German

de-DE

Greek

el-GR

Hungarian

hu-HU

Indonesian

id-ID

Italian

it-IT

Korean

ko-KR

Korean written in the Latin script.

ko-Latn-KR

Lithuanian

lt-LT

Malay

ms-MY

Norwegian

nb-NO

Polish

pl-PL

Portuguese (Brazil)

pt-BR

Portuguese (Portugal)

pt-PT

Russian written in the Cyrillic script.

ru-RU

Russian written in the Latin script.

ru-Latn-RU

Russian written in the Cyrillic script.


Cyrillic script used where possible.

ru-Cyrl-RU

Slovak

sk-SK

Slovenian

sl-SI

Spanish (Castilian)

es-ES

Spanish (Mexico)

es-MX

Swedish

sv-SE

Thai

th-TH

Turkish

tr-TR

Default language algorithm

The best match will be chosen based on the following algorithm.

  1. Every name and name_[language] tag provided in the tile is being matched from left to right. Partial match is allowed. For example:

    • If [language] exactly match, the language is selected.

    • If [language] does not have a match for a region, but a script subtag is available for another primary language subtag, then this other language will be used.

  2. If there are multiple matches for a region, then the one with highest priority is used.

  3. If there is no match then NGT (Neutral Ground Truth) is used.

Handling label translations

Version 2 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{
2 ...
3 "id": "Places - Capital",
4 "layout": {
5 "text-anchor": "center",
6 "text-field": ["coalesce",["get", "name_en-GB"],["get", "name"]],
7 "text-font": ["Noto-Bold"],
8 "text-justify": "auto",
9 "text-letter-spacing": 0.05,
10 ...
11 }
12 ...
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{
2 ...
3 "id": "POI",
4 "layout": {
5 "text-anchor": "center",
6 "text-field": ["concat",["coalesce",["get', "name_pl-PL"],["get", "name"]], "\n", ["get", "sub_text"]],
7 "text-font": ["Noto-Bold"],
8 "text-justify": "auto",
9 "text-letter-spacing": 0.05,
10 ...
11 }
12 ...
13}

List of supported restrictions

Restriction

Description

max_weight

Max gross (total) weight.


float
max_axle_weight

Max weight per axle.


float
max_height

Maximum height allowed.


float
max_axle_count

Maximum number of axles.


integer
no_entry

No entry of a specified vehicle type.

max_width

Maximum width allowed.


float
max_length

Maximum length allowed.


float
speed_limit

Maximum speed allowed.


integer
hazmat_restriction

Type of general hazmat restriction. See:

General load type mapping section


integer
hazmat_class_explosives

Hazmat restriction with explosives dangerous goods class. See:

Vehicle dangerous goods load type mapping section


integer
hazmat_class_gases

Hazmat restriction with the gases dangerous goods class. See:

Vehicle dangerous goods load type mapping section


integer
hazmat_class_flammable_liquids

Hazmat restriction with the flammable liquids dangerous goods class. See:

Vehicle dangerous goods load type mapping section


integer
hazmat_class_flammable_solids

Hazmat restriction with the flammable solids dangerous goods class. See:

Vehicle dangerous goods load type mapping section


integer
hazmat_class_oxidizing_and_organic

Hazmat restriction with the oxidizing and organic dangerous goods class. See:

Vehicle dangerous goods load type mapping section


integer
hazmat_class_toxic_and_infectious

Hazmat restriction with the toxic and infectious dangerous goods class. See:

Vehicle dangerous goods load type mapping section


integer
hazmat_class_radioactive

Hazmat restriction with the radioactive dangerous goods class. See:

Vehicle dangerous goods load type mapping section


integer
hazmat_class_corrosives

Hazmat restriction with the corrosives dangerous goods class. See:

Vehicle dangerous goods load type mapping section


integer
hazmat_class_miscellaneous

Hazmat restriction with the miscellaneous dangerous goods class. See:

Vehicle dangerous goods load type mapping section


integer
adr_restriction_category

Vehicle ADR category. See:

Vehicle ADR category type mapping section


string
no_commercial_vehicle

Commercial vehicles are not allowed.

List of supported units

Value

Description

0Kilometer per hour
1Gallon
2Percentage
3Mile per hour
4Metric ton
5Centimeter
6Meter
7Liter
8Short Ton
9Inch
10Foot

General load type mapping

Value

General load type

0General_Hazardous_Materials
1Explosive_Materials
2Goods_Harmful_To_Water

Dangerous goods load type mapping

Value

Dangerous goods load type

0Explosives
1Gases
2Flammable_Liquids
3Flammable_Solids
4Oxidizing_And_Organic_Substance
5Toxic_And_Infectious_Substance
6Radioactive_Material
7Corrosives
8Miscellaneous_Dangerous_Goods

Adr category type mapping

Value

ADR category

BADR category B
CADR category C
DADR category D
EADR category E