Tile
Service version: 1.0
Last edit: 2019.02.21
On this page
Purpose
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 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. 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 | ||
1 Layer for future use. Not supported yet. |
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 | ||
2 Deprecated layer. Please use Cartographic Label equivalent. |
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 |
Run this endpoint
You can easily run this and other endpoints.
- Go to the TomTom API Explorer page.
- Click an endpoint.
- Click Try it out.
- Enter/select all required parameter values and any optional parameter values.
- At the bottom of the form, click Execute.
- 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.
http|https://baseURL/map/versionNumber/tile/layer/style/zoom/X/Y.format?key=*****
&view=view
&language=language
curl command
curl -XGET 'https://baseURL/map/versionNumber/tile/layer/style/zoom/X/Y.format?key=*****
&view=view
&language=language'
Request parameters
The following elements are used in calls to generate all vector tile layers.
Required parameters | |
---|---|
Parameter | Description |
baseURL string |
The base URL for calling TomTom services. Value: api.tomtom.com Other values: [a|b|c|d].api.tomtom.com See the Host Name Cycling section for details on aliases. |
versionNumber integer |
The version of the service to call. Value: The current version is 1 . |
layer string |
Layer of the tile to be rendered. Values:
|
style string |
Style of the tile to be rendered. Value: main |
zoom integer |
Zoom level of the tile to be rendered. Value: 0..22 |
X integer |
The x coordinate of the tile on a zoom grid. Value: 0..2 zoom -1 |
Y integer |
The y coordinate of the tile on a zoom grid. Value: 0..2 zoom -1 |
format string |
The format of the Response. Value: pbf |
key string |
An API Key valid for the requested service. Value: Your valid API Key. |
Optional parameters | |
Parameter | Description |
view string |
A geopolitical view. Default value: See the following Default view mapping section. Other values:
|
language string |
The language to be used for labels returned in the Response.
Default value: |
Default language algorithm
The best match will be chosen based on the following algorithm.
- 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.
- If there are multiple matches for a region, then the one with highest priority is used.
- 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 , Unified
|
India |
Default view: IN Other available views: None |
Morroco |
Default view: MA Other available views: Arabic , AR , IN , IL , MA , PK
|
Pakistan |
Default view: PK Other available views: Arabic , AR , IN , IL , MA , Unified
|
Bahrain, Kuwait, Oman, Qatar, Saudi Arabia, the United Arab Emirates |
Default view: Arabic Other available views: AR , IN , IL , MA , PK , Unified
|
Others |
Unified Other available views: Arabic , AR , IN , IL , MA , PK
|
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 |
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-SL |
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
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/traffic/map/4/tile/flow/relative/1/0/0.pbf?key=*****
The second would be:
http://b.api.tomtom.com/traffic/map/4/tile/flow/relative/1/0/0.pbf?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.
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 |
---|---|
|
|
Example 2.
Zoom level = 5, hybrid-main style
Request | Response |
---|---|
|
|
Example 3.
Zoom level = 4, labels-main style
Request | Response |
---|---|
|
|
HTTP Response codes
Code | Meaning and Possible Causes |
---|---|
200 |
OK |
400 |
Bad request: Probably malformed syntax.
|
403 |
Forbidden: The supplied API Key is not valid for this Request. |
403 |
Forbidden: The 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. |
HTTP Response headers
The following data table lists HTTP Response headers of particular interest to clients of the Maps Vector Tile API.
Header | Description |
---|---|
Access-Control-Allow-Origin |
The Maps Vector Tile API allows cross-origin resource sharing (CORS). Value: * |