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

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&language=language

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=language

curl command

curl '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&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 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

HTTP Response headers

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

▲ Return to top