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

Examples

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
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

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 parameters

Description

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 parameters

Description

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 parameters

Description

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.


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 headers

Description

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>

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 name

Language 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.

Country

Default 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


Allowed zoom level / bbox combinations

Zoom level

Max longitude difference

Max 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

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
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

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.
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

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

Code

Meaning and possible causes

200OK
400

Bad 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.

403

Forbidden:

  • 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.

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 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.

Header

Description

Access-Control-Allow-Origin

The Static Image Service allows cross-origin resource sharing (CORS). Value: *

Content-Length

Contains information about the size of the response body.


Value: <decimal number>

Content-Type

Indicates the media type of the resource returned.


Values: image/png and image/jpeg.

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 generated automatically by the service. For details check

RFC 4122

.
Value: <string>