Sorry, you need to enable JavaScript to visit this website.

Static Image

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, hybrid and labels. Each can be served in two different styles - main and night.

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 - provides label information only (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 - general full-colour scheme with default TomTom colours.
  • night - modification of the main theme, it is changed to be less invasive than main while using it at night.

 

Request

Format

The generic map call format is as follows:

	<http|https>://<baseURL>/map/<versionNumber>/staticimage?key=<apiKey>[&zoom=<zoom>](&center=<centerPointCoords>[&width=<width>][&height=<height>])|(&bbox=<boundingBox>)[&format=<format>][&layer=<layer>][&style=<style>][&view=<geopoliticalView>]

Examples

	GET http://api.tomtom.com/map/1/staticimage?key=<apiKey>&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=<apiKey>&zoom=9&bbox=1.355233,42.982261,24.980233,56.526017&format=png&layer=labels&style=night&view=IN

Communication through both HTTP and HTTPS is supported.

Parameters

The table below describes all of the parameters that can be used in a request. Required parameters must be used or the call will fail.

Parameter Description Req'd? Type / Values Default Value
baseURL base URL for calling TomTom services Yes api.tomtom.com
/versionNumber Version of the service to call.
The current version is 1
Yes 1
layer= Map layer requested.
If layer parameter is set to hybrid or labels - format parameter has to be set to png
This is due to alpha-layer requirement for serving labels and hybrid layers. User will receive HTTP 400 if in such case other format was selected.
Usage of a value outside of the given set will result in server sending a HTTP 400 response.
No basic|hybrid|labels basic
style= Map style to be returned
Usage of a value outside of the given set will result in server sending a HTTP 400 response.
No main|night main
format= Image format to be returned
Usage of a value outside of the given set will result in server sending a HTTP 400 response.
No
  • png
  • jpg
  • jpeg
png
key= Authorization key for access to the API Yes API Key
zoom= Desired zoom level of the map.
Zoom must be within range: 0-20, otherwise a HTTP 400 response will be sent.
No 0 - 22 12
center= Center point coordinates.
Usage of center is mutually exclusive with usage of bbox.
If both are used - service will return a HTTP 400 response.
EPSG:3857 projection is used. (Note that EPSG:3857 is functionally equivalent to EPSG:900913/EPSG:3785)
Yes lon,lat
Longitude within range: <-180;180>
Latitude within range: <-85;85>
width= Width of the resulting image, in pixels.
Width must be a positive integer in range of 1 to 8192, otherwise a HTTP 400 response will be sent.
No Positive integer within range: 1-8192 512
height= Height of the resulting image, in pixels.
Height must be a positive integer in range of 1 to 8192, otherwise a HTTP 400 response will be sent.
No Positive integer within range: 1-8192 512
bbox= Bounding box.
Usage of bbox is mutually exclusive with usage of center.
EPSG:3857 projection is used. (Note that EPSG:3857 is functionally equivalent to EPSG:900913/EPSG:3785)
If both are used - service will return a HTTP 400 response.
Values have to be in this exact order: minLon, minLat, maxLon, maxLat and maxLat > minLat - otherwise service will return a HTTP 400 response.
One can ask for longitudes on both sides of 180th meridian - thus all combination of minLon and maxLon are valid.
Yes minLon,minLat,maxLon,maxLat
Longitude within range: <-180;180>
Latitude within range: <-85;85>
view= Geopolitical view
Usage of a value outside of the given set will result in server sending a HTTP 400 response.
No
  • Unified
  • IL
  • IN
  • MA
  • PK
  • AR
  • Arabic
See  default view mapping.

Default view mapping

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

Country Default view Other available views
India IN
Israel IL Unified
Others Unified Arabic, AR, IN, IL, MA, PK

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=<apiKey>&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=<apiKey>&zoom=5&bbox=-180,-85,1,0&format=jpg&layer=basic&style=main&view=Unified

Response

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 bbox parameter for latitude
  • layer containing alpha channel is requested in format not supporting the alpha channel

This code is returned if the required parameters of the request were malformed. A detailed exception explanation is returned in a response in form of Service Exception Report.

403 Forbidden:

  • supplied API key is not valid for the request
  • the requested view is not available in the country where the request was sent from
500 Internal Server Error: There is a problem with the Static Map Service.
503 Service currently unavailable.

Response Headers

The table below lists HTTP response headers of particular interest to clients of the Maps WMS API.

Header Description Values
Access-Control-Allow-Origin Static Image Service allows cross-origin resource sharing (CORS). *