Maps APIStatic 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>](¢er=<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¢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=<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 |
| 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 |
|
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:
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:
|
| 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). | * |