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

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, while 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, ect.) delivered in one of the specified vector formats. Format of the tile is formally described using 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 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 according to the schema defined here. The data is mapped to feature layers.  At this moment there are known following layers in 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

Points (Points Of Interest)

Capital city Large city Medium city Small city
Town Village Airport POI Railway station
Country name Ocean name 2 National park name Airport name 2
State name State name short

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 Other label

Roads

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

Tunnels

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

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

1 - layer for future use. Not supported yet.
2 - deprecated layer. Please use Cartographic Label equivalent.

Request Parameters

Format

The generic tile call format is as follows:


<http|https>://<baseURL>/map/<versionNumber>/tile/<layer>/<style>/<zoom>/<X>/<Y>.<format>?key=<apiKey>[&view=<view>][&language=<language>]

Communication through both HTTP and HTTPS is supported.

Common Parameters

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

Parameter Description Req'd? Type / Values Default Value
baseURL base URL for calling TomTom services Yes

api.tomtom.com 
[a|b|c|d].api.tomtom.com 
See the Host Name Cycling section for details on aliases.

/versionNumber Version of the service to call. The current version is 1 Yes 1
/layer Layer of tile to be rendered Yes
  • basic
  • hybrid
  • labels
/style Style of tile to be rendered Yes main
/zoom Zoom level of tile to be rendered Yes 0..22
/X x coordinate of tile on zoom grid Yes 0..2 zoom -1
/Y y coordinate of tile on zoom grid Yes 0..2 zoom -1
format Format of the response. Yes pbf
key= API Key valid for requested service Yes API Key
view= Geopolitical view No
  • Unified
  • IL
  • IN
  • MA
  • PK
  • AR
  • Arabic
See  default view mapping. 
language= Language to be used for labels returned in response. Should be one of supported IETF language tags described here or one of custom language tags. When data in specified language is not available for a specific label,  default language  is used. No See  list of supported languages  NGT

Default language algorithm

 

The best match will be chosen based on 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 match - exactly the requested language is selected
  • if requested primary language subtag does not have match for a region, but script subtag is available for other primary language subtag then this other laguage will be used

 

 

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

3. If there is no match then NGT is used.

Default view mapping

Default view is recognized based on the country the request came from.

Country Default view Other available views
India IN
Israel IL Unified
Others Unified Arabic, AR, IN, IL, MA, PK

List of supported languages

Language Name Language Tag Description
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
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 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

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 and 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 speed up performance of map rendering greatly.

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=<apiKey>

The second would be:

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

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

For more information go here.

Response

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 example responses below 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
http://api.tomtom.com/map/1/tile/basic/main/0/0/0.pbf?
 key=<apiKey>
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

Request Response
http://api.tomtom.com/map/1/tile/hybrid/main/5/4/8.pbf?key=<apiKey>
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
http://api.tomtom.com/map/1/tile/labels/main/4/9/5.pbf?key=<apiKey>
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

 

Http Response Codes

Code Meaning and Possible Causes
200 OK
400 Bad request: Probably malformed syntax

  • 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
  • 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 zoom level)
  • 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 zoom level)
  • requested view is not supported
403 Forbidden: Supplied API key is not valid for this request
403 Forbidden: Requested view is not available in your country
500 Internal Server Error: There is a problem with the TomTom Maps Vector Tile service
503 Service currently unavailable.

 

Response Headers

The table below lists HTTP response headers of particular interest to clients of the Maps Vector Tile API.

Header Description Values
Access-Control-Allow-Origin The Maps Vector Tile API allows cross-origin resource sharing (CORS). *