Tile

Service version: 1
Last edit: 2022.08.15

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

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

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

curl command format

GET
Request curl command
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.

Required parametersDescription
baseURL
string
The base URL for calling TomTom services.
Values:
versionNumber
string
The version of the service to call.
Value: The current version is 1.
layer
string
Layer of the tile to be rendered.
Values:
  • basic
  • hybrid
  • labels
  • poi
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 parametersDescription
view
string
A geopolitical view.
Default value: See the following Default view mapping section.
Other values: Unified, IL, IN, MA, PK, AR, Arabic, RU,TR, CN, KR*
language
string
The language to be used for labels returned in the response. It should be one of the supported IETF language code tags described here or one of the 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.
* 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.

Optional headersDescription
Accept-EncodingContains the content encoding (usually a compression algorithm), that the client is able to understand.
Value: gzip
If-None-MatchContains 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-IDSpecifies 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>

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.

CountryDefault view
ArgentinaAR
Other available views: Arabic, CN, IN, IL, KR*, MA, PK, RU, TR, Unified
IndiaIN
Other available views: None
MoroccoMA
Other available views: Arabic, AR, CN, IN, IL, KR*, PK, RU, TR, Unified
PakistanPK
Other available views: Arabic, AR, CN, IN, IL, KR*, MA, RU, TR, Unified
RussiaRU
Other available views: Arabic, AR, CN, IN, IL, KR*, MA, PK, TR, Unified
TürkiyeTR
Other available views: Arabic, AR, CN, IN, IL, KR*, MA, PK, RU, Unified
ChinaCN
Other available views: Arabic, AR, IN, IL, KR*, MA, PK, RU, TR, Unified
Bahrain, Kuwait, Oman, Qatar,
Saudi Arabia, the United Arab Emirates
Arabic
Other available views: AR, CN, IN, IL, KR*, MA, PK, RU, TR, Unified
OthersUnified
Other available views: Arabic, AR, CN, IN, IL, KR*, MA, PK, RU, TR
* Only available under kr-api.tomtom.com, see Available region specific contents.

List of supported languages

Language nameLanguage 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.
Arabicar
Bulgarianbg-BG
Chinese (Taiwan)zh-TW
Chinese (Simplified)zh-CN
Czechcs-CZ
Danishda-DK
Dutchnl-NL
English (Australia)en-AU
English (Canada)en-CA
English (Great Britain)en-GB
English (New Zealand)en-NZ
English (USA)en-US
Finnishfi-FI
Frenchfr-FR
Germande-DE
Greekel-GR
Hungarianhu-HU
Indonesianid-ID
Italianit-IT
Koreanko-KR
Lithuanianlt-LT
Malayms-MY
Norwegiannb-NO
Polishpl-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
Slovaksk-SK
Sloveniansl-SI
Spanish (Castilian)es-ES
Spanish (Mexico)es-MX
Swedishsv-SE
Thaith-TH
Turkishtr-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:

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

The second would be:

GET
Request URL using b.api.tomtom.com
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.

RequestResponse
https://api.tomtom.com/map/1/tile/basic/main/0/0/0.pbf?key={Your_API_Key}
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

RequestResponse
https://api.tomtom.com/map/1/tile/hybrid/main/5/4/8.pbf?key={Your_API_Key}
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

RequestResponse
https://api.tomtom.com/map/1/tile/labels/main/4/9/5.pbf?key={Your_API_Key}
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

FieldDescription
detailedError
object
Main object of the error response.
code
string
One of a server-defined set of error codes.
message
string
A human-readable description of the error code.
Error response example - JSON format
1{
2 "detailedError" : {
3 "code" : "BAD_REQUEST",
4 "message" : "Invalid tile position arguments"
5 }
6}
Error response example - XML format
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

CodeMeaning & possible causes
200OK
304Not Modified: The tile has not been modified. This code is returned when the If-None-Match request header is used and its value matches the ETag of the requested tile.
400Bad 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.
403Forbidden:
  • The supplied API Key is not valid for this request.
  • The requested view is not available in the country from where the request was sent.
429Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.
500Internal Server Error: There is a problem with the TomTom Maps Vector Tile service.
503Service currently unavailable.

Response headers

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

HeaderDescription
Access-Control-Allow-OriginThe Maps Vector Tile API allows cross-origin resource sharing (CORS).
Value: * Universal.
Cache-ControlContains directives for a caching mechanism.
Value: max-age=<decimal number>
Content-EncodingIndicates which encodings were applied to the response body.
Value: gzip
Content-LengthContains information about the size of the response body.
Value: <decimal number>
Content-TypeIndicates the media type of the resource returned.
Value: image/pbf
DateContains the date and time at which the message was originated.
Value: <http-date>
ETagContains an identifier for a specific version of resource.
Value: W/"2fdbd61f30456"
ExpiresContains the date after which the response is considered outdated.
Value: http-date
Transfer-EncodingSpecifies the form of encoding used to safely transfer response to the user. If this header is specified, the Content-Length header will be absent.
Value: chunked
Tracking-IDAn 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>