Developer

Static Image

Service version: 1
Last edit: 2023.08.01

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

Arabic

ar

Bulgarian

bg-BG

Chinese (Taiwan)

zh-TW

Chinese (Simplified)

zh-CN

Czech

cs-CZ

Danish

da-DK

Dutch

nl-NL

English (Australia)

en-AU

English (Canada)

en-CA

English (Great Britain)

en-GB

English (New Zealand)

en-NZ

English (USA)

en-US

Finnish

fi-FI

French

fr-FR

German

de-DE

Greek

el-GR

Hungarian

hu-HU

Indonesian

id-ID

Italian

it-IT

Korean

ko-KR

Lithuanian

lt-LT

Malay

ms-MY

Norwegian

nb-NO

Polish

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

Slovak

sk-SK

Slovenian

sl-SI

Spanish (Castilian)

es-ES

Spanish (Mexico)

es-MX

Swedish

sv-SE

Thai

th-TH

Turkish

tr-TR

Default view mapping

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

Country

Default view

Argentina

AR


Other available views: Arabic , CN , IN , IL , KR *, MA , PK , RU , TR , Unified

India

IN


Other available views: None

Morocco

MA


Other available views: Arabic , AR , CN , IN , IL , KR *, PK , RU , TR , Unified

Pakistan

PK


Other available views: Arabic , AR , CN , IN , IL , KR *, MA , RU , TR , Unified

Russia

RU


Other available views: Arabic , AR , CN , IN , IL , KR *, MA , PK , TR , Unified

Türkiye

TR


Other available views: Arabic , AR , CN , IN , IL , KR *, MA , PK , RU , Unified

China

CN


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

Others

Unified


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

0

360

170

1

360

170

2

360

170

3

360

170

4

360

170

5

180

85

6

90

42.5

7

45

21.25

8

22.5

10.625

9

11.25

5.3125

10

5.625

2.65625

11

2.8125

1.328125

12

1.40625

0.6640625

13

0.703125

0.33203125

14

0.3515625

0.166015625

15

0.17578125

0.0830078125

16

0.087890625

0.0415039063

17

0.0439453125

0.0207519531

18

0.0219726563

0.0103759766

19

0.0109863281

0.0051879883

20

0.0054931641

0.0025939941

21

0.00274658205

0.00129699705

22

0.00137329102

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

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

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

Code

Meaning and possible causes

200

OK

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.

503

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