Hillshade Tile
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 Map Styles.
Tile Sizes
- 514 x 514 pixels Each tile includes a 1-pixel buffer around the edges, taken from neighbor tiles.
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.
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
https://{baseURL}/map/{versionNumber}/tile/{layer}/{type}/{zoom}/{X}/{Y}.{format}?key={Your_API_Key}
Example
https://api.tomtom.com/map/1/tile/hill/main/8/68/120.png?key={Your_API_Key}
curl command format
curl 'https://{baseURL}/map/{versionNumber}/tile/{layer}/{type}/{zoom}/{X}/{Y}.{format}?key={Your_API_Key}
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 parameters | Description |
|---|---|
string | The base URL for calling TomTom services. Value: |
string | The version of the service to call. Value: The current version is |
string | Layer of the tile to be requested. Value: |
string | Type of the tile to be requested. Value: |
integer | Zoom level of the tile to be rendered. Value: |
integer | The x coordinate of the tile on a zoom grid. Value: 0..2 zoom -1 |
integer | The y coordinate of the tile on a zoom grid. Value: 0..2 zoom -1 |
string | The format of the response. Value: |
string | An API Key valid for the requested service. Value: Your valid API Key. |
Request headers
The following table lists HTTP request headers of particular interest to clients of the Maps Raster Tile API Hillshade endpoint.
Optional headers | Description |
|---|---|
Contains the content encoding (usually a compression algorithm), that the client is able to understand. Value: | |
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: | |
Tracking-ID | Specifies an identifier for the request. It can be used to trace a call.
The value must match the regular expression
Value: |
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 = | Response (Zoom = |
|---|---|
|  |
Example 2: Zoom = 13
Request (Zoom = | Response (Zoom = |
|---|---|
|  |
Error response
The Maps Raster Tile API Hillshade 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 |
|---|---|
object | Main object of the error response. |
string | One of a server-defined set of error codes. |
string | A human-readable description of the error code. |
Error response example
1{2 "detailedError" : {3 "code" : "BAD_REQUEST",4 "message" : "Invalid tile position arguments"5 }6}
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
Code | Meaning & possible causes |
|---|---|
| OK |
| Not Modified : The tile has not been modified. This code is
returned when the |
| Bad request : Probably malformed syntax.
|
| Forbidden :
|
| Too Many Requests : Too many requests were sent in a given amount of time for the supplied API Key. |
| Internal Server Error : There is a problem with the TomTom Maps Hillshade Tile API service. |
| 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.
Header | Description |
|---|---|
The Maps Raster Tile API allows cross-origin resource sharing (CORS). Value: | |
Contains directives for a caching mechanism. Value: | |
Indicates which encodings were applied to the response body. Value: | |
Contains information about the size of the response body. Value: | |
Indicates the media type of the resource returned. Value: | |
Contains the date and time at which the message was originated. Value: | |
Contains an identifier for a specific version of resource. Value: | |
Contains the date after which the response is considered outdated. Value: | |
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: | |
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. |