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

Raster Tile


Service version: 1
Last edit: 2021.06.23

On this page


The Maps Raster Tile API endpoint 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 the: 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

The following tiles sizes are currently supported:

  • 256 x 256 pixels: This is better suited for lower resolution displays and clients sensitive to internet data transfer usage.
  • 512 x 512 pixels: This is created for displays with high resolutions.

Run this endpoint

You can easily run this and other endpoints.

  1. Go to the TomTom API Explorer page.
  2. Click an endpoint.
    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  3. Review the Response.

▲ Return to top

Request data

HTTPS method: GET

URL format

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Optional parameters are shown in plain text.

Communication through both HTTP and HTTPS is supported. The generic tile call format is as follows:


curl command

curl -XGET 'https://baseURL/map/versionNumber/tile/layer/style/zoom/X/Y.format?key=Your_API_Key&tileSize=tileSize&view=geopoliticalView&language=language'

▲ Return to top

Request parameters

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

  • Required parameters must be used or the call will fail.
  • Parameters and values are case-sensitive.
  • Optional parameters may be used.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
Required parameters
Parameter Description
The base URL for calling TomTom services.
Other values: [a|b|c|d]
See the Host Name Cycling section for details on aliases.
The version of the service to call.
Value: The current version is 1.
Layer of the tile to be rendered.
  • basic
  • hybrid
  • labels
Style of the tile to be rendered.
  • main
  • night
Zoom level of the tile to be rendered.
Value: 0..22
The x coordinate of the tile on a zoom grid.
Value: 0..2 zoom -1
The y coordinate of the tile on a zoom grid.
Value: 0..2 zoom -1
The format of the Response.
  • jpg
  • png
Note: The jpg format is only supported for layer=basic, style=main, and zoom<7.
An API Key valid for the requested service.
Value: Your valid API Key.
Optional parameters
Parameter Description
The tile size dimension in pixels.
Default value: 256
Other value: 512
A geopolitical view. Usage of a value outside of the given set will result in the server sending a HTTP 400 Response.
Default value: See the following Default view mapping section.
Other values:
  • Unified
  • IL
  • IN
  • MA
  • PK
  • AR
  • Arabic
  • RU
  • TR
  • CN
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.

HTTP Request headers

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

Required headers
Note: There are no required headers in this endpoint.
Optional headers
Header Description
Accept-Encoding Contains the content encoding (usually a compression algorithm), that the client is able to understand.
Value: gzip
If-None-Match Contains 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-ID Specifies 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>

▲ Return to top

Default language algorithm

The best match will be chosen based on following algorithm.

  1. Every IETF language subtag provided in the "language" parameter is being matched from left to right. A partial match is allowed. For example:
    • All requested language subtags exactly match when 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 other primary language subtags, then this other laguage will be used.
  2. If there are multiple matches for a region, then the one with the highest priority is used.
  3. If there is no match then NGT (Neutral Ground Truth) is used.

▲ Return to top

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
Chinese (Simplified) zh-CN
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.
Slovak sk-SK
Slovenian sl-SI
Spanish (Castilian) es-ES
Spanish (Mexico) es-MX
Swedish sv-SE
Thai th-TH
Turkish tr-TR

▲ Return to top

Default view mapping

Default view is recognised based on the country the Request came from.

Country Default view
Argentina AR
Other available views: Arabic, CN, IN, IL, MA, PK, RU, TR, Unified
India IN
Other available views: None
Morocco MA
Other available views: Arabic, AR, CN, IN, IL, PK, RU, TR, Unified
Pakistan PK
Other available views: Arabic, AR, CN, IN, IL, MA, RU, TR, Unified
Russia RU
Other available views: Arabic, AR, CN, IN, IL, MA, PK, TR, Unified
Turkey TR
Other available views: Arabic, AR, CN, IN, IL, MA, PK, RU, Unified
China CN
Other available views: Arabic, AR, IN, IL, MA, PK, RU, TR, Unified
Bahrain, Kuwait, Oman, Qatar,
Saudi Arabia, the United Arab Emirates
Other available views: AR, CN, IN, IL, MA, PK, RU, TR, Unified
Others Unified
Other available views: Arabic, AR, CN, IN, IL, MA, PK, RU, TR

▲ Return to top

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:
  • 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:

The second would be:

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

▲ Return to top

Response data

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 view basic night view
hybrid hybrid main view hybrid night view
labels labels main view labels night view

▲ Return to top

512 x 512 pixels

basic basic main 512
labels labels main 512

▲ Return to top

Response examples

Example 1

Whole world at zoom = 0.

Request Response
Basic main zoom = 0:
basic main zoom 0
Basic night zoom = 0:
basic night zoom 0
Note: There is 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.

▲ Return to top

Example 2

Europe at zoom = 4.

Request Response
Basic main zoom = 4:
basic main zoom 4
Hybrid main zoom = 4:
hybrid main zoom 4
Labels main zoom = 4:
labels main zoom 4
Basic night zoom = 4:
basic night zoom 4
Hybrid night zoom = 4:
hybrid night zoom 4
Labels night zoom = 4:
labels night zoom 4

▲ Return to top

Example 3

Amsterdam at zoom = 17

Request Response
Basic main zoom = 17:
basic main zoom = 17
Hybrid main zoom = 17:
hybrid main zoom = 17
Labels main zoom = 17:
labels main zoom = 17
Basic night zoom = 17:
basic night zoom = 17
Hybrid night zoom = 17:
hybrid night zoom = 17
Labels night zoom = 17:
labels night zoom = 17

▲ Return to top

Error Response

The Map Display API Raster 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

Field Description
Main object of the error response.
One of a server-defined set of error codes.
A human-readable description of the error code.

Error response example

JSON format
  "detailedError" : {
    "code" : "BAD_REQUEST",
    "message" : "Invalid tile position arguments"
XML format
<errorResponse description="Invalid tile position arguments" errorCode="400" version="1.0.54-mascoma">
    <message>Invalid tile position arguments</message>

▲ Return to top

HTTP response codes

Code Meaning and possible causes
200 OK.
304 Not 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.
400 Bad 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).
403 Forbidden:
  • 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.
429 Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.
500 Internal Server Error: There is a problem with the TomTom Maps Raster Tile service.
503 Service currently unavailable.

HTTP Response headers

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

Header Description
Access-Control-Allow-Origin The Maps Raster Tile API allows cross-origin resource sharing (CORS).
Value: *
Cache-Control Contains directives for a caching mechanism.
Value: max-age=<decimal number>
Content-Encoding Indicates which encodings were applied to the Response body.
Value: gzip
Content-Length Contains information about the size of the Response body.
Value: <decimal number>
Content-Type Indicates the media type of the resource returned.
  • image/png
  • image/jpeg
Date Contains the date and time at which the message was originated.
Value: <http-date>
ETag Contains an identifier for a specific version of resource.
Value: W/"2fdbd61f30456"
Expires Contains the date after which the Response is considered outdated.
Value: http-date
transfer-encoding Specifies the form of encoding used to safely transfer Response to the user. If this header is specified, Content-Length header will be absent.
Value: chunked
Tracking-ID An 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>

▲ Return to top