Tile

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 2⁴⁴ 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 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 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.

Layers

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

2D Areas (Polygons)

▲ Return to top

Points (Points Of Interest)

▲ Return to top

POI Categories

▲ Return to top

Cartographic Labels

Roads

▲ Return to top

Tunnels

Toll roads

▲ Return to top

Toll tunnels

Other lines

▲ Return to top

Tags

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

Roads

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

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
  keys:
    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
  values:
    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
    tags:
      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
    geometry:
      move_to: 712,413
      line_to: -27,6
      line_to: -45,8

Shield icon shape types

Shield icon fill and stroke colors

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.

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.

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.

http|https://baseURL/map/versionNumber/tile/layer/style/zoom/X/Y.format?key=Your_API_Key&view=view&language=language

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.

HTTP Request headers

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

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

▲ Return to top

List of supported languages

▲ 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 api.tomtom.com 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:
  • a.api.tomtom.com
  • b.api.tomtom.com
  • c.api.tomtom.com
  • d.api.tomtom.com
• 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:

http://a.api.tomtom.com/map/1/tile/basic/main/1/0/0.pbf?key=Your_API_Key

The second would be:

http://b.api.tomtom.com/map/1/tile/basic/main/1/0/0.pbf?key=Your_API_Key

and so on up until d.api.tomtom.com. When more than four tiles are being requested, start back again at a.api.tomtom.com.

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.

http://api.tomtom.com/map/1/tile/basic/main/0/0/0.pbf?key=Your_API_Key

layers:3
 lake:
   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
 ocean:
   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

http://api.tomtom.com/map/1/tile/hybrid/main/5/4/8.pbf?key=Your_API_Key

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

http://api.tomtom.com/map/1/tile/labels/main/4/9/5.pbf?key=Your_API_Key

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

HTTP Response headers

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