Static Image

Service version: 1
Last edit: 2022.08.15

Purpose

The Static Image service renders a user-defined, rectangular image containing a map section. A user can select one of 23 zoom levels ranging from 0 to 22 for it.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

Layers and styles

A user can select from predefined layers and styles for the map. The Static Image service supports the following layers:

  • basic layer
  • hybrid layer
  • labels layer

Each layer can be served in two different styles: main style and night style.

Layers

Basic

Contains full map data, i.e., polygons, roads, borders, and labels.

Hybrid

Contains borders, roads, and labels (all the map features, except geographic polygons). It can be overlaid on another map layer (such as satellite imagery) in order to produce a hybrid map.

Labels

Only provides label information (the same as the basic map layer). It can be used in situations where traffic tubes or other overlaid information cover labels of the base map layer. The labels are precisely placed in order to align with the labels on the basic layer. Because overlaying requires transparency, all overlay images must be requested in png format.

Styles

Styles define two colour schemes:

  • main: Defines the general full-colour scheme with default TomTom colours.
  • night: Defines the modification of the main theme, it is changed to be less invasive than main while using it at night.

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}/map/{versionNumber}/staticimage?key={Your_API_Key}&center={centerPointCoords}&bbox={boundingBox}&zoom={zoom}&width={width}&height={height}&format={format}&layer={layer}&style={style}&view={geopoliticalView}

Examples

GET
Example request URL
https://api.tomtom.com/map/1/staticimage?key={Your_API_Key}&zoom=9&center=13.567893,46.112341&format=jpg&layer=basic&style=main&width=1305&height=748&view=Unified&language=en-GB
GET
Example request URL
https://api.tomtom.com/map/1/staticimage?key={Your_API_Key}&zoom=9&bbox=23.355233,55.982261,24.980233,56.526017&format=png&layer=labels&style=night&view=IN&language=en-GB

curl command format

GET
curl request URL
curl 'https://api.tomtom.com/map/1/staticimage?key={Your_API_Key}&zoom=9&center=13.567893,46.112341&format=jpg&layer=basic&style=main&width=1305&height=748 &view=Unified &language=en-GB'

Request parameters

The following data table describes the parameters that can be used in a request. Required parameters must be used or the call will fail.

Important: the center parameter and the bbox parameter are mutually exclusive. Either of these parameters are required in a request, but not both. If you use both of these parameters in the same request, the call will fail with a 400 error. See the Mutually exclusive parameters section in the following table for more information.

Required parametersDescription
baseURL
string
The base URL for calling TomTom services.
Value: api.tomtom.com
versionNumber
string
The version of the service to call.
Value: The current version is 1.
key
string
The Authorization key for access to the API.
Value: Your valid API Key.
Mutually exclusive parametersDescription
center
float
Center point coordinates. Usage of center is mutually exclusive with the usage of bbox. If both are used, the service will return a HTTP 400 error response. EPSG:3857 projection is used. (Note that EPSG:3857 is functionally equivalent to EPSG:900913/EPSG:3785)
Value: lon,lat
  • Longitude within range: -180;180
  • Latitude within range: -85;85
bbox
float
Bounding box. Usage of bbox is mutually exclusive with the usage of center. If both are used, the service will return a HTTP 400 error response. EPSG:3857 projection is used. (Note that EPSG:3857 is functionally equivalent to EPSG:900913/EPSG:3785) Values have to be in this exact order: minLon, minLat, maxLon, maxLat, and maxLat > minLat. Otherwise, the service will return a HTTP 400 error response. You can ask for longitudes on both sides of the 180th meridian; thus, all combinations of minLon and maxLon are valid.
Values: minLon,minLat,maxLon,maxLat
  • Longitude within range: -180;180
  • Latitude within range: -85;85
Optional parametersDescription
layer
string
Default value: basic
Other values: hybrid and labels.
style
string
The map style to be returned. Usage of a value outside of the given set will result in the server sending a HTTP 400 response.
Default value: main
Other value: night
format
string
The image format to be returned. Usage of a value outside of the given set will result in the server sending a HTTP 400 response.
Default value: png
Other values: jpg and jpeg.
zoom
integer
The desired zoom level of the map. Zoom must be within the range of: 0-20, otherwise a HTTP 400 response will be sent.
Default value: 12
Other values: 0 - 22
width
integer
The width of the resulting image, in pixels. Width must be a positive integer in the range of 1 to 8192, otherwise a HTTP 400 response will be sent.
Default value: 512
Other values: A positive integer within the range of: 1-8192.
height
integer
The height of the resulting image, in pixels. Height must be a positive integer in the range of 1 to 8192, otherwise a HTTP 400 response will be sent.
Default value: 512
Other values: A positive integer within the range of: 1-8192.
view
string
The geopolitical view. Usage of a value outside of the given set will result in the server sending a HTTP 400 response.
Default value: See the following Default view mapping section.
Other values: Unified, IL, IN, MA, PK, AR, Arabic, RU, TR, CN, KR*
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.
* Only available under kr-api.tomtom.com, see Available region specific contents.

Request headers

The following table lists HTTP request headers of particular interest to clients of the Maps Static Image API endpoint. Note: There are no required headers in this endpoint.

Optional headersDescription
Tracking-IDSpecifies 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 language algorithm

The best match will be chosen based on the following algorithm.

  1. Every IETF language subtag provided in the language parameter is being matched from left to right. A partial match is allowed. For example:
    • All requested language subtags exactly match when the requested language is selected.
    • If the requested primary language subtag does not have a match for a region, but a script subtag is available for other primary language subtags, then this other laguage will be used.
  2. If there are multiple matches for a region, then the one with the highest priority is used.
  3. If there is no match then NGT (Neutral Ground Truth) is used.

List of supported languages

Language nameLanguage tag
Neutral Ground Truth (custom)NGT
Official languages for all regions in local scripts if available.
Neutral Ground Truth - Latin exonyms (custom)NGT-Latn
Latin script will be used if available.
Arabicar
Bulgarianbg-BG
Chinese (Taiwan)zh-TW
Chinese (Simplified)zh-CN
Czechcs-CZ
Danishda-DK
Dutchnl-NL
English (Australia)en-AU
English (Canada)en-CA
English (Great Britain)en-GB
English (New Zealand)en-NZ
English (USA)en-US
Finnishfi-FI
Frenchfr-FR
Germande-DE
Greekel-GR
Hungarianhu-HU
Indonesianid-ID
Italianit-IT
Koreanko-KR
Lithuanianlt-LT
Malayms-MY
Norwegiannb-NO
Polishpl-PL
Portuguese (Brazil)pt-BR
Portuguese (Portugal)pt-PT
Russian written in the Cyrillic script.ru-RU
Russian written in the Latin script.ru-Latn-RU
Russian written in the Cyrillic script.
Cyrillic script used where possible.
ru-Cyrl-RU
Slovaksk-SK
Sloveniansl-SI
Spanish (Castilian)es-ES
Spanish (Mexico)es-MX
Swedishsv-SE
Thaith-TH
Turkishtr-TR

Default view mapping

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

CountryDefault view
ArgentinaAR
Other available views: Arabic, CN, IN, IL, KR*, MA, PK, RU, TR, Unified
IndiaIN
Other available views: None
MoroccoMA
Other available views: Arabic, AR, CN, IN, IL, KR*, PK, RU, TR, Unified
PakistanPK
Other available views: Arabic, AR, CN, IN, IL, KR*, MA, RU, TR, Unified
RussiaRU
Other available views: Arabic, AR, CN, IN, IL, KR*, MA, PK, TR, Unified
TürkiyeTR
Other available views: Arabic, AR, CN, IN, IL, KR*, MA, PK, RU, Unified
ChinaCN
Other available views: Arabic, AR, IN, IL, KR*, MA, PK, RU, TR, Unified
Bahrain, Kuwait, Oman, Qatar,
Saudi Arabia, the United Arab Emirates
Arabic
Other available views: AR, CN, IN, IL, KR*, MA, PK, RU, TR, Unified
OthersUnified
Other available views: Arabic, AR, CN, IN, IL, KR*, MA, PK, RU, TR
* Only available under kr-api.tomtom.com, see Available region specific contents.

Allowed zoom level / bbox combinations

Zoom levelMax longitude differenceMax latitude difference
0360170
1360170
2360170
3360170
4360170
518085
69042.5
74521.25
822.510.625
911.255.3125
105.6252.65625
112.81251.328125
121.406250.6640625
130.7031250.33203125
140.35156250.166015625
150.175781250.0830078125
160.0878906250.0415039063
170.04394531250.0207519531
180.02197265630.0103759766
190.01098632810.0051879883
200.00549316410.0025939941
210.002746582050.00129699705
220.001373291020.00064849852

Examples

GET
Correct request URL uses &bbox
https://api.tomtom.com/map/1/staticimage?key={Your_API_Key}&zoom=5&bbox=-180,-85,0,0&format=jpg&layer=basic&style=main&view=Unified
GET
Incorrect request URL uses &bbox
https://api.tomtom.com/map/1/staticimage?key={Your_API_Key}&zoom=5&bbox=-180,-85,1,0&format=jpg&layer=basic&style=main&view=Unified

Response data

Error response

The Map Display API Static Map service for an invalid request returns a response body in plain text or JSON format. The plain text 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.

Plain text format

Bad request

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.
details
array
Optional field. Details about an error. Contains objects which have the following properties:
  • code
  • message
  • target
target
string
Name of an invalid parameter.

Error response example

Error response - JSON
1{
2 "detailedError" : {
3 "code" : "BAD_REQUEST",
4 "message" : "Bad request",
5 "details": [
6 {
7 "code": "OUT_OF_RANGE_VALUE",
8 "message": "Invalid zoom 23. Expected zoom in range 0-22.",
9 "target": "zoom"
10 },
11 {
12 "code": "INVALID_PARAM",
13 "message": "Invalid format png2. Supported formats are: png, jpg, jpeg.",
14 "target": "format"
15 }
16 ]
17 }
18}

Response codes

CodeMeaning and possible causes
200OK
400Bad Request: Received by the interface, but there is an error in the request, such as:
  • One or more of the required parameters is missing.
  • Unsupported or unrecognized parameter value.
  • Two or more mutually exclusive parameters are used in one query.
  • When max- and min- values are switched in the bbox parameter for latitude.
  • A layer containing an alpha channel is requested in a format not supporting the alpha channel.

This HTTP response code is returned if the required parameters of the request were malformed. A detailed exception explanation is returned in a response in the form of a Service Exception Report.
403Forbidden:
  • The supplied API Key is not valid for the request.
  • The requested view is not available in the country from where the request was sent.
429Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.
500Internal Server Error: There is a problem with the Static Map Service.
503Service currently unavailable

Response headers

The following data table lists HTTP response headers of particular interest to clients of the Maps Static Image API endpoint.

HeaderDescription
Access-Control-Allow-OriginThe Static Image Service allows cross-origin resource sharing (CORS).Value: *
Content-LengthContains information about the size of the response body.
Value: <decimal number>
Content-TypeIndicates the media type of the resource returned.
Values: image/png and image/jpeg.
Tracking-IDAn 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>