Sorry, you need to enable JavaScript to visit this website.
PricingContact
Maps API
Get your key

Static Image

 

Service version: 1
Last edit: 2019.10.21

On this page

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.

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.

Run this endpoint

You can easily run this and other endpoints.

  1. Go to the TomTom API Explorer page.
  2. Click an endpoint.

    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  3. Review the Response.

▲ Return to top

Request data

HTTPS method: GET

Communication through both HTTP and HTTPS is supported.

The generic map call format is as follows:

URL format

For ease of viewing and identification:

  • Required constants and parameters are shown in bold text.
  • Mutually exclusive parameters are shown in italics text.
  • Optional parameters are shown in plain text.
http|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 http://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
GET 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

curl command

curl -XGET 'http://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'

▲ Return to top

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
Parameter 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
Parameter 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
Parameter Description
layer
string 		Default value: basic
Other values:

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

HTTP Request headers

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

Required headers
Note: There are no required headers in this endpoint.
Optional headers
Header 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 view mapping

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

Country Default view Allowed views
Argentina AR Arabic, IN, IL, MA, PK, RU, TR, Unified
India IN —
Morocco MA Arabic, AR, IN, IL, PK, RU, TR, Unified
Pakistan PK Arabic, AR, IN, IL, MA, RU, TR, Unified
Bahrain, Kuwait, Oman, Qatar, Saudi Arabia, the United Arab Emirates Arabic AR, IN, IL, MA, PK, RU, TR, Unified
Others Unified Arabic, AR, IN, IL, MA, PK, RU, TR

▲ Return to top

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

Correct: GET http://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
Incorrect: GET http://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

▲ Return to top

Response data

HTTP 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

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

▲ Return to top

You are here

Maps API / Maps API Documentation / Raster / Static Image