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

Raster Tile

The Maps Raster Tile API renders map data that is divided into gridded sections called tiles. Tiles are square images in various sizes which are available at 23 different zoom levels, ranging from 0 to 22. For zoom level 0, the entire earth is displayed on one single tile, while at zoom level 22, the world is divided into 244 tiles (see: Zoom Levels and Tile Grid).

Tile Layers and Styles

The Maps Raster service supports the following tile layers: basic, hybrid and labels. Each can be served in two different styles - main and night.

Basic tiles contain mapping data such as polygons, road shapes, borders and labels. In addition to the basic map tiles, the service provides overlay tiles. These are partially transparent tiles containing map geometry or labels but not the full map. They can be layered with other TomTom or third party map tiles to create consolidated views:

  • The labels overlay provides the same label information as the standard map tile. It can be used in situations where traffic tubes or other overlaid information covers the labels on the base map layer. The labels are precisely placed to align with the labels on the standard layer.
  • The hybrid overlay provides all the features from the map data except geographic polygons. It contains borders, roads, and labels, and can be overlaid on other tiles (such as satellite imagery) to produce hybrid tiles displaying TomTom map data.

Because overlaying requires transparency, all overlay tiles must be requested with a format of png.

Tile Sizes

Currently following tiles sizes are supported:

  • 256 x 256 pixels - better suited for lower resolution displays and clients sensitive to internet data transfer usage
  • 512 x 512 pixels - created for displays with high resolutions. Available for layers "basic" and "labels" in style "main" only.



The generic tile call format is as follows:


Communication through both HTTP and HTTPS is supported.

Common Parameters

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

Parameter Description Req'd? Type / Values Default Value
baseURL base URL for calling TomTom services Yes
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
  • night
/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
  • jpg
  • png

The jpg format is only supported for layer=basic, style = main and zoom < 7

key= API Key valid for requested service Yes API Key
[tileSize=] Tile size dimension in pixels No
  • 256
  • 512

The 512 tile size is supported only for style = main with layer = basic or labels

[view=] Geopolitical view
Usage of a value outside of the given set will result in server sending a HTTP 400 response.
  • 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.

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

Default view mapping

Default view is recognised 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

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 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,, and 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:<apiKey>

The second would be:<apiKey>

...and so on up until When more than four tiles are being requested, start back again at

For more information go here.


The Maps Raster API, for a single request, returns one square tile in png or jpg format.

256 x 256 pixels

  main night
basic basic_main basic_night
hybrid hybrid_main hybrid_night
labels labels_main labels_night


512 x 512 pixels


basic basic_main_512
labels labels_main_512

Response examples

Example 1

Whole world at zoom = 0

Request Response<apiKey>

Note: Please, note that there's no data for labels and roads at this zoom level, so any different combination of layer and style will cause a transparent tile to be returned.

Example 2

Europe at zoom = 4

Request Response<apiKey>

Example 3

Amsterdam at zoom = 17

Request Response<apiKey>


Http Response Codes

Code Meaning and Possible Causes
200 OK
302 Found: URL redirection
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
  • 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 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 zoom level)
403 Forbidden:

  • supplied API key is not valid for this request
  • the requested view is not available in the country where the request was sent from
410 Gone: Request for unsupported format
500 Internal Server Error: There is a problem with the TomTom Maps Raster Tile service


Response Headers

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

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