TomTom LogoDocs
Products
Resources
Pricing
Sign in
Map Display API
Documentation
API Explorer
Launch Map Maker
Map Maker Documentation

Hillshade Tile

Service version: 2Last edit: 2025.10.06TomTom Orbis Maps
Hillshade Tile Orbis Maps Display API

Purpose

The Maps Raster Hillshade Tile API endpoint provides terrain elevation data that is divided into gridded sections called tiles. It can be used for rendering hillshade that shows the topographical shape of hills and mountains. Tiles are square images with a size of: 514 x 514 pixels. The tiles are available at 14 different zoom levels, ranging from 0 to 13. See the: Zoom Levels and Tile Grid .

Tile image format

The Maps Raster Tile API Hillshade service supports the png format.

Overlay

The overlay can be applied to the Maps Raster Hillshade Tiles using Assets API .

Tile Sizes

  • 514 x 514 pixels Each tile includes a 1-pixel buffer around the edges, taken from neighbor tiles.

Tile with margins

Elevation data

Every pixel in the tile combines 3 colors: red, green, and blue. It contains an elevation value(in meters), which can be decoded with the formula:

height = -10000 + ((Red * 256 * 256 + Green * 256 + Blue) * 0.1)

Example: For pixel rgb(1, 134, 170) which have color values:

  • Red: 1
  • Green: 134
  • Blue: 170

Using it with formula:

height = -10000 + ((1 * 256 * 256 + 134 * 256 + 170) * 0.1)

This equation gives us an elevation value equal to 1 meter above sea level.

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}/maps/orbis/display/hillshade/tile/{zoom}/{X}/{Y}?key={Your_API_Key}&apiVersion=2&type={type}

Example

get
Request example
https://api.tomtom.com/maps/orbis/display/hillshade/tile/8/68/120?key={Your_API_Key}&apiVersion=2

curl command format

get
Request curl command
curl 'https://{baseURL}/maps/orbis/display/hillshade/tile/{zoom}/{X}/{Y}?key={Your_API_Key}&apiVersion=2&type={type}

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.
Value: api.tomtom.com

zoom
integer

Zoom level of the tile to be rendered.
Value: 0..13

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

key
string

An API Key valid for the requested service.
Please note that using the TomTom-Api-Key header is recommended over apiVersion query parameters for improved security.
Value: Your valid API Key.
Optional parametersDescription

apiVersion
integer

Specifies the version of the API to use. If set, this parameter overrides the value in the TomTom-Api-Version header. Value: The current version is 2.

type string

Type of the tile to be requested. Default value: dem

Request headers

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

Required headersDescription

TomTom-Api-Key string

An API Key valid for the requested service.
Preferred method for authentication. Using the header is recommended over apiVersion query parameters for improved security.
Value: Your valid API Key.

TomTom-Api-Version integer

Specifies the version of the API to use for the request. This header allows clients to explicitly select which version of the API they wish to interact with.

  • The value must be an integer representing the API version.
  • For this service, the current supported version is 2.
Value:2
Optional headersDescription
Accept

Indicates which content types (expressed as MIME types) supported by the endpoint the sender is able to understand. If any of the given content types are not supported, the server will fall back to the default one.
Value: image/png

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>

Response data

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

Response examples

Example 1: Zoom = 8

Request (Zoom = 8 )Response (Zoom = 8 )
https://api.tomtom.com/maps/orbis/display/hillshade/tile/8/68/120?key={Your_API_Key}&apiVersion=2Zoom 8

Example 2: Zoom = 13

Request (Zoom = 13 )Response (Zoom = 13)
https://api.tomtom.com/maps/orbis/display/hillshade/tile/13/2196/3879?key={Your_API_Key}&apiVersion=2Zoom 13

Error response

The Maps Raster Tile API Hillshade service for an invalid request returns a response body in JSON format.

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
{
  "detailedError" : {
    "code" : "BAD_REQUEST",
    "message" : "Invalid tile position arguments"
  }
}

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.

  • Invalid format value.

  • Zoom n is out of range 0 <= zoom <= 13: 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.

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 Hillshade Tile API service.

503

Service is currently unavailable.

HTTP response headers

The following table lists HTTP response headers of particular interest to clients of the Maps Raster Tile API Hillshade 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: "<hexadecimal number>"

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 automatically generated by the service. For details check RFC 4122 .
Value: <string>