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.
- Go to the TomTom API Explorer page.
-
Click an endpoint.
- Click Try it out.
- Enter/select all required parameter values and any optional parameter values.
- At the bottom of the form, click Execute.
- Review the Response.
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¢er=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¢er=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¢er=13.567893,46.112341&format=jpg&layer=basic&style=main&width=1305&height=748&view=Unified'
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.
Value:
|
bbox float |
Bounding box.
Values:
|
Optional parameters | |
Parameter | Description |
layer string |
Default value: basic Other values:
|
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:
|
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:
|
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.
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 |
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
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:
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:
|
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:
|
Tracking-ID |
An identifier for the Request.
Value: <string> |