Satellite Tile

Service version: 1

Last edit: 2024.11.18

TomTom Orbis Maps

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 Satellite Tile API endpoint provides satellite map data that is divided into gridded sections called tiles. Tiles are square images with a size of: 256 x 256 pixels. The tiles are available at 20 different zoom levels, ranging from 0 to 19. For zoom level 0, the entire earth is displayed on one single tile, while at zoom level 19, the world is divided into 2³⁸ tiles. See the: Zoom Levels and Tile Grid.

Data Source

Satellite imagery data comes from Maxar Satellite Imagery for all supported zoom levels. Most of the detailed imagery for urban areas was captured in or after 2021.

Tile image format

The Maps Raster Tile API Satellite service supports the jpg format.

Overlay

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

Tile Sizes

The following tiles size is currently supported:

256 x 256 pixels

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/map-display/tile/satellite/{zoom}/{X}/{Y}.{format}?key={Your_API_Key}&apiVersion=1

curl command format

get

Request curl command

curl 'https://{baseURL}/maps/orbis/map-display/tile/satellite/{zoom}/{X}/{Y}.{format}?key={Your_API_Key}&apiVersion=1'

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
Parameter	Description
`baseURL` string	The base URL for calling TomTom services. Value: `api.tomtom.com`
`layer` string	Layer of the tile to be requested. Value: `satellite`
`zoom` integer	Zoom level of the tile to be rendered. Value: `0..19`
`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: `jpg`
`key` string	An API Key valid for the requested service. Value: Your valid `API Key`.

Optional parameters	Description
`apiVersion` integer	A version of the api to call. If the parameter is set, it will overwrite the value stored in the TomTom-Api-Version header. Value: The current version is `1`.
`style` string	Style of the tile to be requested. Value: `main`

Request headers

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

Optional headers	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>`
`TomTom-Api-Version` integer	Contains a version of the API to call. Value: The current version is `1`.

Response data

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

Response examples

Example 1: Whole world at zoom = `0`

Request (Zoom = `0` )	Response (Zoom = `0` )
`https://api.tomtom.com/maps/orbis/map-display/tile/satellite/0/0/0.jpg?key={Your_API_Key}`

Example 2: Europe at zoom = `4`

Request (Zoom = `4` )	Response (Zoom = `4` )
`https://api.tomtom.com/maps/orbis/map-display/tile/satellite/4/8/5.jpg?key={Your_API_Key}`

Example 3: Amsterdam at zoom = `17`

Request (Zoom = `17`)	Response (Zoom = `17`)
`https://api.tomtom.com/maps/orbis/map-display/tile/satellite/17/67296/43062.jpg?key={Your_API_Key}`

Error response

The Maps Raster Tile API Satellite 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
`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

Code	Meaning & 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 <= 19: 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 Satellite 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 satellite 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. Value: `image/jpg`
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, 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>`