Developer

Raster Tile

Service version: 1
Last edit: 2024.11.18
TomTom Orbis Maps

Important notes:

Purpose

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 basic tile layer. It can be served in two different styles: street-light and street-dark.

  • The basic raster tiles contain mapping data such as polygons, road shapes, borders, labels, and road icons.

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.

Request data

HTTPS method: GET

For ease of viewing and identification:

  • 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 these values. The generic URL format is as follows.

URL format

get
Request URL
https://{baseURL}/maps/orbis/map-display/tile/{zoom}/{X}/{Y}.{format}?apiVersion=1&key={Your_API_Key}&style={style}&tileSize={tileSize}&view={view}&language={language}

curl command format

get
Request curl command
curl 'https://{baseURL}/maps/orbis/map-display/tile/{zoom}/{X}/{Y}.{format}?apiVersion=1&key={Your_API_Key}&style={style}&tileSize={tileSize}&view={view}&language={language}'

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.
Required parametersDescription

baseURL
string

The base URL for calling TomTom services.
Values:

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

key
string

An API Key valid for the requested service.
Value: Your valid API Key.

Optional parametersDescription

apiVersion
integer

A version of the API to call. This parameter will overwrite the value stored in the TomTom-Api-Version header if this parameter is set.
Value: The current version is 1.

style
string

Style of the tile to be rendered.
Values:

  • street-light

  • street-dark

tileSize
integer

The tile size dimension in pixels.
Default value: 256
Other value: 512

view
string

A geopolitical view.
Default value: See the following Default view mapping section.
Other values:

  • Unified

  • IN

  • PK

  • AR

  • Arabic

  • KR

  • RS

  • MY

  • CL

  • DZ

  • PH

  • BN

  • TW

  • MA

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.

Request headers

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

Required headersDescription

TomTom-Api-Version
integer

Contains a version of the API to call.
Value: The current version is 1.

Optional headersDescription
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>

Default view mapping

Default view is recognized based on the country the request came from.

CountryDefault view
India

IN
Other available views: None

Pakistan

PK
Other available views: Unified, IN, AR, Arabic, KR, RS, MY, CL, DZ, PH, BN, TW, MA, TR, IL, VN

Argentina

AR
Other available views: Unified, IN, PK, Arabic, KR, RS, MY, CL, DZ, PH, BN, TW, MA, TR, IL, VN

Bahrain, Kuwait, Oman, Qatar, Saudi Arabia, the United Arab Emirates

Arabic
Other available views: Unified, IN, PK, AR, KR, RS, MY, CL, DZ, PH, BN, TW, MA, TR, IL, VN

Korea

KR
Other available views: Unified, IN, PK, AR, Arabic, RS, MY, CL, DZ, PH, BN, TW, MA, TR, IL, VN

Serbia

RS
Other available views: Unified, IN, PK, AR, Arabic, KR, MY, CL, DZ, PH, BN, TW, MA, TR, IL, VN

Malaysia

MY
Other available views: Unified, IN, PK, AR, Arabic, KR, RS, CL, DZ, PH, BN, TW, MA, TR, IL, VN

Chile

CL
Other available views: Unified, IN, PK, AR, Arabic, KR, RS, MY, DZ, PH, BN, TW, MA, TR, IL, VN

Algeria

DZ
Other available views: Unified, IN, PK, AR, Arabic, KR, RS, MY, CL, PH, BN, TW, MA, TR, IL, VN

Philippines

PH
Other available views: Unified, IN, PK, AR, Arabic, KR, RS, MY, CL, DZ, BN, TW, MA, TR, IL, VN

Brunei

BN
Other available views: Unified, IN, PK, AR, Arabic, KR, RS, MY, CL, DZ, PH, TW, MA, TR, IL, VN

Taiwan

TW
Other available views: Unified, IN, PK, AR, Arabic, KR, RS, MY, CL, DZ, PH, BN, MA, TR, IL, VN

Morocco

MA
Other available views: Unified, IN, PK, AR, Arabic, KR, RS, MY, CL, DZ, PH, BN, TW, TR, IL, VN

Türkiye

TR
Other available views: Unified, IN, PK, AR, Arabic, KR, RS, MY, CL, DZ, PH, BN, TW, MA, IL, VN

Israel

IL
Other available views: Unified, IN, PK, AR, Arabic, KR, RS, MY, CL, DZ, PH, BN, TW, MA, TR, VN

Vietnam

VN
Other available views: Unified, IN, PK, AR, Arabic, KR, RS, MY, CL, DZ, PH, BN, TW, MA, TR, IL

Others

Unified
Other available views: IN, PK, AR, Arabic, KR, RS, MY, CL, DZ, PH, BN, TW, MA, TR, IL, VN

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/maps/orbis/map-display/tile/1/0/0.png?apiVersion=1&style=street-light&key={Your_API_Key}

The second would be:

get
Request URL using b.api.tomtom.com
https://b.api.tomtom.com/maps/orbis/map-display/tile/1/0/0.png?apiVersion=1&style=street-light&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 Maps Raster API, for a single request, returns one square tile in png format.

256 x 256 pixels

LayerMainNight
basicbasic street-lightbasic street-dark

512 x 512 pixels

LayerMain
basicbasic street-light 512

Response examples

Example 1

**Whole world at zoom = 0 **

RequestResponse

Basic street-light zoom = 0:
https://api.tomtom.com/maps/orbis/map-display/tile/0/0/0.png?apiVersion=1&style=street-light&key={Your_API_Key}

basic street light zoom 0

Basic street-dark zoom = 0:
https://api.tomtom.com/maps/orbis/map-display/tile/0/0/0.png?apiVersion=1&style=street-dark&key={Your_API_Key}

basic street-dark zoom 0

Example 2

**Europe at zoom = 4 **

RequestResponse

Basic street-light zoom = 4:
https://api.tomtom.com/maps/orbis/map-display/tile/4/8/5.png?apiVersion=1&style=street-light&key={Your_API_Key}

basic street-light zoom 4

Basic street-dark zoom = 4:
https://api.tomtom.com/maps/orbis/map-display/tile/4/8/5.png?apiVersion=1&style=street-dark&key={Your_API_Key}

basic street-dark zoom 4

Example 3

**Amsterdam at zoom = 17 **

RequestResponse

Basic street-light zoom = 17:
https://api.tomtom.com/maps/orbis/map-display/tile/17/67296/43062.png?apiVersion=1&style=street-light&key={Your_API_Key}

basic street-light zoom = 17

Basic street-dark zoom = 17:
https://api.tomtom.com/maps/orbis/map-display/tile/17/67296/43062.png?apiVersion=1&style=street-dark&key={Your_API_Key}

basic street-dark zoom = 17

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

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

Error response example - JSON
1{
2  "detailedError": {
3    "code": "BAD_REQUEST",
4    "message": "Invalid tile position arguments"
5  }
6}
Error response example - XML
1<errorResponse description="Invalid tile position arguments" errorCode="400" version="1.0.54-mascoma">
2    <code>BAD_REQUEST</code>
3    <message>Invalid tile position arguments</message>
4  </detailedError>
5</errorResponse>

Response codes

CodeMeaning & 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.

Response headers

The following table lists HTTP response headers of particular interest to clients of the Map Display API Raster Tile endpoint.

HeaderDescription
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.
Value: image/png

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 the response to the user. If this header is specified, the 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>