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.

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.

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.

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.

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

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

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

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'

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

HTTP Request headers

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

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.

▲ Return to top

List of supported languages

Default view mapping

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

▲ Return to top

Allowed zoom level / bbox combinations

Examples

Correct: GET 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

Incorrect: GET 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

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

Error response example

JSON format

{
      "detailedError" : {
        "code" : "BAD_REQUEST",
        "message" : "Bad request",
        "details": [
          {
            "code": "OUT_OF_RANGE_VALUE",
            "message": "Invalid zoom 23. Expected zoom in range 0-22.",
            "target": "zoom"
          },
          {
            "code": "INVALID_PARAM",
            "message": "Invalid format png2. Supported formats are: png, jpg, jpeg.",
            "target": "format"
          }
        ]
      }
    }

▲ Return to top

HTTP response codes

HTTP Response headers

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