Hillshade Tile
Important notes:
- This TomTom Orbis API is in public preview.
- This API is powered by TomTom Orbis Maps.
- See the TomTom Orbis Maps documentation for more information.
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.
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
https://{baseURL}/maps/orbis/map-display/tile/{layer}/{zoom}/{X}/{Y}.{format}?key={Your_API_Key}&apiVersion=1&type={type}
Example
https://api.tomtom.com/maps/orbis/map-display/tile/hillshade/8/68/120.png?key={Your_API_Key}&apiVersion=1
curl command format
curl 'https://{baseURL}/maps/orbis/map-display/tile/{layer}/{zoom}/{X}/{Y}.{format}?key={Your_API_Key}&apiVersion=1&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 parameters | Description |
---|---|
string | The base URL for calling TomTom services. Value: |
string | Layer 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. |
Optional parameters | Description |
---|---|
| A version of the api to call. If the parameter is set, it will overwrite the value stored in TomTom-Api-Version header.
Value: The current version is |
string | Type of the tile to be requested. Default value: |
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. |