Sorry, you need to enable JavaScript to visit this website.



Service version: 1
Last edit: 2020.02.06

On this page


Similar to Maps Raster Tile, the Maps Vector Tile serves data on zoom levels ranging from 0 to 22.

  • For zoom level 0, the entire earth is displayed on a single tile.
  • At zoom level 22, the world is divided into 244 tiles. See: Zoom Levels and Tile Grid.

The Maps Vector Service delivers geographic map data packaged in a vector representation of squared sections called vector tiles.

  • Each tile includes pre-defined collections of map features (points, lines, road shapes, water polygons, building footprints, etc.) delivered in one of the specified vector formats.
  • The format of the tile is formally described using the protobuf schema.

Tiles Layers and Styles

The Vector Maps Service supports the following tile layers: basic, hybrid, and labels.

Unlike raster tiles there is no difference in data served between main and night styles. The vector data consists of layers with their own names and geometry. The client determines how to present this data to the end user, for example which colours to use for which features.

  • The basic vector tiles contain mapping data such as polygons, road shapes, borders, labels and road icons.
  • The labels vector tiles provide the same label information as the basic vector tiles. The labels are precisely placed to align with the labels on the basic vector tiles.
  • The hybrid vector tiles provide all the features from the basic layer except geographic polygons. It contains borders, road networks, labels and road icons.

Tiles Resolution

Visible geometry is stored as coordinates in the range 0-4095. Coordinate 0,0 is defined as the top-left corner of the tile.

TomTom Vector format

TomTom Vector Tile format is a proprietary binary format created by using Google Protocol Buffers to serialize the data as defined in the Vector tile schema. The data is mapped to feature layers. Besides the protobuf layers, the protobuf tags are also used to further describe the features.


At this moment, the following items are the known layers in the protobuf format.

2D Areas (Polygons)

Built-up area National or state park City park Woodland
Regional park National park State or province park County park
Cemetery Moor or heathland Beach or dune Zoo
Industrial harbor area Industrial area Stadium Hospital
Shopping Amusement park University School
Golf Parking area Sports hall Institution
Airport Runway Military Other water
Intermittent water Lake Sea 1 Ocean 1
Ocean or sea River Sand Forest
Subway Station Factory building Place of worship Hospital building
School building Hotel building Cultural Facility Railway Station
Government Administration Office Pedestrian Deck Town shore Town garden path
Town swimming pool Town paved area Town walkway Town carriageway divider
Town factory ground Town school ground Town hospital ground Town railway ground
Town greens Town grass Town water body Other building
Other town block Meridian Sidewalk Breakwater
Pool Park
1 Layer for future use. Not supported yet.

▲ Return to top

Points (Points Of Interest)

Capital city Large city Medium city Small city
Town Village Airport POI Railway station
Country name National park name 2 State name State name short
POI 3 Ferry terminal - -
2 Deprecated layer. Please use the Cartographic Label equivalent.
3 To see available categories check POI Categories.

▲ Return to top

POI Categories

Bus stop Mountain peak Hill Ridge
Valley Reef Government office Post office
Fire station Police station - -

▲ Return to top

Cartographic Labels

Airport label Amusement area label Cemetery label Park/Garden label
Stadium label Military Territory label Golf Course label Hospital label
Industrial area label Other water body label Woodland label Prison label
University/School label Intermittent water label Island label Lake label
Zoo label Reservation label Shopping centre label Landmark label
River label Ocean label Sea label National park label
Other label Museum label - -


Motorway International road Major road Secondary road
Connecting road Major local road Local road Minor local road

▲ Return to top


Motorway tunnel International road tunnel Major road tunnel Secondary road tunnel
Connecting road tunnel Major local road tunnel Local road tunnel Minor local road tunnel

Toll roads

Toll motorway Toll international road Toll major road Toll secondary road
Toll connecting road Toll major local road Toll local road Toll minor local road

▲ Return to top

Toll tunnels

Toll motorway tunnel Toll international road tunnel Toll major road tunnel Toll secondary road tunnel
Toll connecting road tunnel Toll major local road tunnel Toll local road tunnel Toll minor local road tunnel

Other lines

Ferry road Pedestrian road Non public road Walkway road
Parking road Railway Country border Disputed country border
State border

▲ Return to top


Each feature may contain additional protobuf tags. Currently, the following tags are used.


Each road may have one or more road shields. The shields are indexed from 0, and described by sets of tags.

Protobuf tags
Tag Description
The name of the road shield icon associated with the road.
Value: For easier referencing and implementation, the name of a roadshield follows one of two formats:
  • shapeType-fillColor-strokeColor-numOfChars: For shields to be re-used 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.
Text to be placed on the road shield icon with the corresponding shield_icon idx.
Value: road number
The color of the text on the road shield icon with the corresponding shield_icon idx.
Value: hexadecimal color code

Example road layer feature with tags

The following examples use a simple textual representation of the serialized binary vector tile data to illustrate how protobuf tags for the road shield may be used.

layer: 0
  name: Motorway
  version: 2
  extent: 4096
    0: shield_icon_0
    1: icon_text_0
    2: shield_icon_text_color_0
    3: shield_icon_1
    4: icon_text_1
    5: shield_icon_text_color_1
    6: shield_icon_2
    7: icon_text_2
    8: shield_icon_text_color_2
    0: canada--1000-3
    1: 104
    2: #000000
    3: canada-ns-1255-2
    4: 28
    5: #FFFFFF
    6: rectangle-white-black-3
    7: 368
  feature: 0
    type: linestring
    id: 0
      shield_icon_0: canada--1000-3
      icon_text_0: 104
      shield_icon_text_color_0: #000000
      shield_icon_1: canada-ns-1255-2
      icon_text_1: 28
      shield_icon_text_color_1: #FFFFFF
      shield_icon_2: rectangle-white-black-3
      icon_text_2: 368
      shield_icon_text_color_2: #000000
      move_to: 712,413
      line_to: -27,6
      line_to: -45,8

Shield icon shape types

rectangle hexagon hexagon2 octagon special01 special02 special03 special04
shield01 shield02 shield03 shield04 shield05 shield06 shield07 shield08
shield09 shield10 shield11 shield12 pentagon circle pill us1
us2 us3 oval diamond                

Shield icon fill and stroke colors

white yellow1 yellow2 yellow3 orange green1 green2 green3 blue1
blue2 blue3 brown1 brown2 red grey anthracite black    

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.
colombia south mexico indonesia taiwan canada usa venezuela southafrica
cuba india australia argentina saudiarabia uae peru korea    

▲ Return to top

Run this endpoint

You can easily run this and other endpoints.

  1. Go to the TomTom API Explorer page.
  2. Click an endpoint.
    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  3. Review the Response.

Request data

HTTPS method: GET

Communication through both HTTP and HTTPS is supported. The generic tile call format is as follows.

URL format

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.

curl command

curl -XGET 'https://baseURL/map/versionNumber/tile/layer/style/zoom/X/Y.format?key=Your_API_Key&view=view&language=language'

▲ Return to top

Request parameters

The following elements are used in calls to generate all vector tile layers.

Required parameters
Parameter Description
The base URL for calling TomTom services.
Other values: [a|b|c|d]
See the Host Name Cycling section for details on aliases.
The version of the service to call.
Value: The current version is 1.
Layer of the tile to be rendered.
  • basic
  • hybrid
  • labels
Style of the tile to be rendered.
Value: main
Zoom level of the tile to be rendered.
Value: 0..22
The x coordinate of the tile on a zoom grid.
Value: 0..2 zoom -1
The y coordinate of the tile on a zoom grid.
Value: 0..2 zoom -1
The format of the Response.
Value: pbf
An API Key valid for the requested service.
Value: Your valid API Key.
Optional parameters
Parameter Description
A geopolitical view.
Default value: See the following Default view mapping section. Other values:
  • Unified
  • IL
  • IN
  • MA
  • PK
  • AR
  • Arabic
  • RU
  • TR
The language to be used for labels returned in the Response.
  • It should be one of the supported IETF language tags or one of custom language tags.
  • When data in a specified language is not available for a specific label, the default language is used.
Default value: NGT (Neutral Ground Truth)
Other values: See the following List of supported languages section.

HTTP Request headers

The following table lists HTTP Request headers of particular interest to clients of the Maps Vector Tile API endpoint.

Required headers
Note: There are no required headers in this endpoint.
Optional headers
Header Description
Accept-Encoding Contains the content encoding (usually a compression algorithm), that the client is able to understand.
Value: gzip
If-None-Match Contains an identifier for a specific version of resource. The server will send back the requested resource, with a 200 HTTP status code, only if it doesn't have an ETag matching the given one.
Value: <string>
Tracking-ID Specifies an identifier for the Request.
  • It can be used to trace a call.
  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.
  • An example of the format that matches this regular expression is a UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1). For details check RFC 4122.
  • If specified, it is replicated in the Tracking-ID Response header.
Value: <string>

▲ Return to top

Default language algorithm

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

  1. Every IETF language subtag provided in "language" parameter is being matched from left to right. Partial match is allowed. For example:
    • All requested language subtags exactly match; the requested language is selected.
    • If requested primary language subtag does not have match for a region, but a script subtag is available for another primary language subtag, then this other laguage 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.

Default view mapping

Default view is recognised based on the country the Request came from.

Country Default view
Argentina Default view: AR
Other available views: Arabic, IN, IL, MA, PK, RU, TR, Unified
India Default view: IN
Other available views: None
Morocco Default view: MA
Other available views: Arabic, AR, IN, IL, PK, RU, TR, Unified
Pakistan Default view: PK
Other available views: Arabic, AR, IN, IL, MA, RU, TR, Unified
Russia Default view: RU
Other available views: Arabic, AR, IN, IL, MA, PK, TR, Unified
Turkey Default view: TR
Other available views: Arabic, AR, IN, IL, MA, PK, RU, Unified
Bahrain, Kuwait, Oman, Qatar,
Saudi Arabia, the United Arab Emirates
Default view: Arabic
Other available views: AR, IN, IL, MA, PK, RU, TR, Unified
Others Unified
Other available views: Arabic, AR, IN, IL, MA, PK, RU, TR

▲ Return to top

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
Lithuanian lt-LT
Malay ms-MY
Norwegian nb-NO
Polish pl-PL
Portuguese (Brazil) pt-BR
Portuguese (Portugal) pt-PT
Russian written in the Cyrlic script. ru-RU
Russian written in the Latin script. ru-Latn-RU
Russian written in the Cyrlic script.
Cyrlic script used where possible.
Slovak sk-SK
Slovenian sl-SI
Spanish (Castilian) es-ES
Spanish (Mexico) es-MX
Swedish sv-SE
Thai th-TH
Turkish tr-TR

▲ Return to top

Host Name Cycling

Most web browsers have a default limitation on the number of active connections that can be allowed to each host.

  • This means if map tiles are being loaded via the host name, they will be loaded one at a time.
  • A trick that can be used to get around this limitation is to cycle through the hosts we have created as aliases.
  • These host names are:
  • By cycling through these four different host names, the web browser will be tricked into retrieving four map tiles at a time rather than just one.
  • This will significantly speed up the performance of map rendering.

For instance, if four map tiles are being requested at zoom level one, you would request the first one as:

The second would be:

and so on up until When more than four tiles are being requested, start back again at

▲ Return to top

Response data

The Vector Maps API, for a single Request, returns a binary Response body which must be deserialized by client code generated by the Google Protocol Buffers compiler.

The following Response examples use a simple textual representation of the serialized binary vector tile data to illustrate the Response content.

Response examples

Example 1

Whole world at zoom = 0, basic-main style.

Request Response
   version: 2
   extent: 255
   features: 371
   keys: 0
   values: 0
   geometry summary:
	 total: 3339
	 commands: 1113
	 move_to: 371
	 line_to: 742
	 close: 371
	 degenerate polygons: 371
	 empty geoms: 0
   version: 2
   extent: 255
   features: 5313
   keys: 0
   values: 0
   geometry summary:
	 total: 47817
	 commands: 15939
	 move_to: 5313
	 line_to: 10626
	 close: 5313
	 degenerate polygons: 5313
	 empty geoms: 0
 country border:
   version: 2
   extent: 255
   features: 199
   keys: 1
   values: 0
   geometry summary:
	 total: 3162
	 commands: 398
	 move_to: 199
	 line_to: 1183
	 close: 0
	 degenerate polygons: 73
	 empty geoms: 0

Example 2.

Zoom level = 5, hybrid-main style

Request Response
layers: 1
state border:
   version: 2
   extent: 16384
   features: 200
   keys: 3
   values: 0
   geometry summary:
	 total: 8384
	 commands: 400
	 move_to: 200
	 line_to: 3792
	 close: 0
	 degenerate polygons: 23
	 empty geoms: 0

Example 3.

Zoom level = 4, labels-main style

Request Response
layers: 8
ocean name:
   version: 2
   extent: 16384
   features: 3
   keys: 3
   values: 1
   geometry summary:
	 total: 18
	 commands: 6
	 move_to: 3
	 line_to: 3
	 close: 0
	 degenerate polygons: 3
	 empty geoms: 0
country name:
   version: 2
   extent: 16384
   features: 7
   keys: 2
   values: 14
   geometry summary:
	 total: 21
	 commands: 7
	 move_to: 7
	 line_to: 0
	 close: 0
	 degenerate polygons: 0
	 empty geoms: 0
capital city:
   version: 2
   extent: 16384
   features: 7
   keys: 2
   values: 14
   geometry summary:
	 total: 21
	 commands: 7
	 move_to: 7
	 line_to: 0
	 close: 0
	 degenerate polygons: 0
	 empty geoms: 0

▲ Return to top

HTTP Response codes

Code Meaning and Possible Causes
200 OK
400 Bad request: Probably malformed syntax.
  • The combination of layer, style, and query parameters is not supported.
  • Zoom n is out of range 0 <= zoom <= 22: The requested zoom level is out of the possible range.
  • x n is out of range [0,m]: The requested x coordinate is out of the possible range (the value of m will vary depending on the zoom level).
  • y n is out of range [0,m]: The requested y coordinate is out of the possible range (the value of m will vary depending on the zoom level).
  • The requested view is not supported.
403 Forbidden: The supplied API Key is not valid for this Request.
403 Forbidden: The requested view is not available in your country.
429 Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.
500 Internal Server Error: There is a problem with the TomTom Maps Vector Tile service.
503 Service currently unavailable.

HTTP Response headers

The following data table lists HTTP Response headers of particular interest to clients of the Maps Vector Tile API endpoint.

Header Description
Access-Control-Allow-Origin The Maps Vector Tile API allows cross-origin resource sharing (CORS).
Value: * Universal.
Cache-Control Contains directives for a caching mechanism.
Value: max-age=<decimal number>
Content-Encoding Indicates which encodings were applied to the Response body.
Value: gzip
Content-Length Contains information about the size of the Response body.
Value: <decimal number>
Content-Type Indicates the media type of the resource returned.
Value: image/pbf
Date Contains the date and time at which the message was originated.
Value: <http-date>
ETag Contains an identifier for a specific version of resource.
Value: W/"2fdbd61f30456"
Expires Contains the date after which the Response is considered outdated.
Value: http-date
transfer-encoding Specifies the form of encoding used to safely transfer Response to the user. If this header is specified, Content-Length header will be absent.
Value: chunked
Tracking-ID An identifier for the Request.
  • If the Tracking-ID header was specified in the Request, it is replicated in the Response.
  • Otherwise, it is generated automatically by the service. For details check RFC 4122.
Value: <string>

▲ Return to top