Tile

Purpose

Similar to the Map Display API 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 the 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.
• The content of the tiles and meaning of each tile layer is described in the tile layers and styles section.

Tiles Layers and Styles

The Vector Maps Service supports the following tile layers: basic, hybrid, labels, and poi. 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 colors 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 of the features from the basic layer except geographic polygons. It contains borders, road networks, labels, and road icons.
• The poi vector tiles provide all of the Points of Interest features.

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.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

Request data

HTTPS method: GET

• Constants and parameters enclosed in curly brackets { } must be replaced with their values.
• Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

URL format

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

curl command format

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

Request parameters

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

• Only available under kr-api.tomtom.com , see Available region specific contents.
  

HTTP request headers

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

Note: There are no required headers in this endpoint.

Default language algorithm

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

1. Every IETF language subtag provided in the 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 the requested primary language subtag does not have a 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.

• Only available under kr-api.tomtom.com , see Available region specific contents.
  

List of supported languages

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:

https://a.api.tomtom.com/map/1/tile/basic/main/1/0/0.png?key={Your_API_Key}

The second would be:

https://b.api.tomtom.com/map/1/tile/basic/main/1/0/0.png?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.

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.

1layers:3
2 lake:
3   version: 2
4   extent: 255
5   features: 371
6   keys: 0
7   values: 0
8   geometry summary:
9	 total: 3339
10	 commands: 1113
11	 move_to: 371
12	 line_to: 742
13	 close: 371
14	 degenerate polygons: 371
15	 empty geoms: 0
16 ocean:
17   version: 2
18   extent: 255
19   features: 5313
20   keys: 0
21   values: 0
22   geometry summary:
23	 total: 47817
24	 commands: 15939
25	 move_to: 5313
26	 line_to: 10626
27	 close: 5313
28	 degenerate polygons: 5313
29	 empty geoms: 0
30 country border:
31   version: 2
32   extent: 255
33   features: 199
34   keys: 1
35   values: 0
36   geometry summary:
37	 total: 3162
38	 commands: 398
39	 move_to: 199
40	 line_to: 1183
41	 close: 0
42	 degenerate polygons: 73
43	 empty geoms: 0

Example 2. Zoom level = 5 , hybrid-main style

1layers: 1
2state border:
3   version: 2
4   extent: 16384
5   features: 200
6   keys: 3
7   values: 0
8   geometry summary:
9	 total: 8384
10	 commands: 400
11	 move_to: 200
12	 line_to: 3792
13	 close: 0
14	 degenerate polygons: 23
15	 empty geoms: 0

Example 3. Zoom level = 4 , labels-main style

1layers: 8
2ocean name:
3   version: 2
4   extent: 16384
5   features: 3
6   keys: 3
7   values: 1
8   geometry summary:
9	 total: 18
10	 commands: 6
11	 move_to: 3
12	 line_to: 3
13	 close: 0
14	 degenerate polygons: 3
15	 empty geoms: 0
16country name:
17   version: 2
18   extent: 16384
19   features: 7
20   keys: 2
21   values: 14
22   geometry summary:
23	 total: 21
24	 commands: 7
25	 move_to: 7
26	 line_to: 0
27	 close: 0
28	 degenerate polygons: 0
29	 empty geoms: 0
30capital city:
31   version: 2
32   extent: 16384
33   features: 7
34   keys: 2
35   values: 14
36   geometry summary:
37	 total: 21
38	 commands: 7
39	 move_to: 7
40	 line_to: 0
41	 close: 0
42	 degenerate polygons: 0
43	 empty geoms: 0

Error response

The Map Display API Vector service for an invalid request returns a response body in XML or JSON format. The XML format is returned by default. To have an error response returned in JSON format, application/json has to be specified in the Accept HTTP request header.

Error response field structure

1{
2  "detailedError": {
3    "code": "BAD_REQUEST",
4    "message": "Invalid tile position arguments"
5  }
6}

1<errorResponse description="Invalid tile position arguments" errorCode="400" version="1.0.54-mascoma">
2  <detailedError>
3    <code>BAD_REQUEST</code>
4    <message>Invalid tile position arguments</message>
5  </detailedError>
6</errorResponse>

Response codes

Response headers

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