Content

Service version: 2
Last edit: 2022.06.28

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.

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 typeValueCoordinatesDescription
MoveTo1x,yIt 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.
LineTo2x,yIt 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.
ClosePath7noneIt 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 = 9 & 0x7 = 2
13 count = 9 >> 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), (326, 969)]

For a POLYGON type feature:

Input:

1layer: 0
2 feature: 0
3 type: POLYGON
4 geometry: [9, 1320, 5622, 18, 1736, 4914, 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 = 9 & 0x7 = 2
13 count = 9 >> 0x3 = 3
14
15 x0′ = 1736, y0′ = 4914
16 decode(x0′) = 660 + ((1736 >> 0x1) ^ (-(1736 & 0x1))) = 1528
17 decode(y0′) = 2811 + ((4914 >> 0x1) ^ (-(4914 & 0x1))) = 5268
18
19 x1′ = 68, y1′ = 612
20 decode(x1′) = decode(x0′) + ((68 >> 0x1) ^ (-(68 & 0x1))) = 1562
21 decode(y1′) = decode(y0′) + ((612 >> 0x1) ^ (-(612 & 0x1))) = 5574
22
23 x2′ = 483, y2′ = 96
24 decode(x2′) = decode(x1′) + ((483 >> 0x1) ^ (-(483 & 0x1))) = 1320
25 decode(y2′) = decode(y1′) + ((96 >> 0x1) ^ (-(96 & 0x1))) = 5622
26 3:
27 command_and_count = 7
28 command = 9 & 0x7 = 7
29 count = 9 >> 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 tagsValuesDescription
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 tagsValuesDescription
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 tagsValuesDescription
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
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.

water

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

Geometry type: POLYGON

water tagsValuesDescription
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 tagsValuesDescription
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 tagsValuesDescription
category
string
permanent_waterThis 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_labelslayer. 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 tagsValuesDescription
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 tagsValuesDescription
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.

CategoryCategory IDPossible subcategoriesSubcategory 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_area9362national_park
cemetery
9362008
9362003
zoo_arboreta_and_botanical_garden9927--
shopping_center7373--
golf_course9911--
stadium7374--
tourist_attraction7376--
place_of_worship7339church
mosque
synagogue
temple
gurudwara
ashram
pagoda
7339002
7339003
7339004
7339005
7339006
7339007
7339008
airport7383--
ferry_terminal7352--
public_transportation_stop9942bus_stop
taxi_stand
coach_stop
streetcar_stop
9942002
9942003
9942005
9942004
railroad_station7380international_railroad_station
national_railroad_station
subway_station
738002
738003
738005
geographic_feature8099mountain_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 tagsValuesDescription
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.

CategoryCategory IDPossible subcategoriesSubcategory 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_pub9376cafe
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_area9362national_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_worship7339church
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_stop9942bus_stop
taxi_stand
coach_stop
streetcar_stop
9942002
9942003
9942005
9942004
railroad_station7380international_railroad_station
national_railroad_station
subway_station
738002
738003
738005
geographic_feature8099mountain_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 tagsValuesDescription
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_lineslayer. 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 tagsValuesDescription
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
trueThis 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
trueThis 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
trueThis 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
trueThis 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.

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 tagsValuesDescription
category
string
country
state
This tag specifies to which category a given feature belongs.
treaty
boolean
trueThis 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
trueThis 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 nameLanguage 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.
Arabicar
Bulgarianbg-BG
Chinese (Taiwan)zh-TW
Chinese (Simplified)zh-CN
Czechcs-CZ
Danishda-DK
Dutchnl-NL
English (Australia)en-AU
English (Canada)en-CA
English (Great Britain)en-GB
English (New Zealand)en-NZ
English (USA)en-US
Finnishfi-FI
Frenchfr-FR
Germande-DE
Greekel-GR
Hungarianhu-HU
Indonesianid-ID
Italianit-IT
Koreanko-KR
Korean written in the Latin script.ko-Latn-KR
Lithuanianlt-LT
Malayms-MY
Norwegiannb-NO
Polishpl-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
Slovaksk-SK
Sloveniansl-SI
Spanish (Castilian)es-ES
Spanish (Mexico)es-MX
Swedishsv-SE
Thaith-TH
Turkishtr-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}