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

Map Styles

 

Service version: 1.0
Last edit: 2020.05.14

On this page

Purpose

The Maps API Resource service delivers resources required to display vector maps. The service consists of the:

  • Metadata method: This retrieves a list of resources of a selected type.
  • Resource method: This retrieves a selected resource.
  • Merged style method: This retrieves a merged style depending on the passed params.
  • Merged sprite method: This retrieves a merged sprite depending on the passed params.

Request data

Metadata method

HTTPS method: GET

URL format

For ease of viewing and identification:

  • Required parameters are shown in bold text.
  • Optional parameters are shown in normal text.

The generic URL format is as follows:

http|https://baseURL/map/versionNumber/resourceType/resourceVersion/resourceVariant/metadata.format?key=Your_API_Key

Examples

http://api.tomtom.com/map/1/style/metadata.xml?key=Your_API_Key
http://api.tomtom.com/map/1/sprite/20.0.0-8/metadata.json?key=Your_API_Key
http://api.tomtom.com/map/1/glyph/20.0.0-8/metadata.jsonp?key=Your_API_Key

curl command

curl 'http://api.tomtom.com/map/1/sprite/20.0.0-8/metadata.json?key=Your_API_Key'

Request parameters (Metadata method)

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Parameters and values are case-sensitive.
  • Optional parameters may be used.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
Required parameters
Parameter Description
baseURL
string
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.
resourceType
string
The type of the requested resource.
Values:
  • style
  • sprite
  • glyph
format
string
The Requested response format.
Values:
  • xml
  • json
  • jsonp
key
string
The authorization key for access to the API.
Value: Your valid API Key.
Optional parameters
Parameter Description
resourceVersion
string
Version of the requested resource. If the version string contains a wildcard, the latest matching version of the resource will be provided.
Values:
  • A version.
  • A partial version ending with a wildcard character, e.g., *, 20.*, 20.0.2-*.
resourceVariant
string
Variant of the requested resource. Can only be used when resourceVersion is provided.
Value: The variant name.

▲ Return to top

Resource method

HTTPS method: GET

URL format

For ease of viewing and identification:

  • Required parameters are shown in bold text.
  • Optional parameters are shown in normal text.

The generic URL format is as follows:

http|https://baseURL/map/versionNumber/resourceType/resourceVersion/resourceVariant/resourceName?key=Your_API_Key

Example

https://api.tomtom.com/map/1/style/20.0.0-8/basic_main.json?key=Your_API_Key
https://api.tomtom.com/map/1/sprite/20.0.0-8/lite/sprite.png?key=Your_API_Key

curl command

curl 'http://api.tomtom.com/map/1/style/20.0.0-8/basic_main.json?key=Your_API_Key'

Request parameters (Resource method)

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Parameters and values are case-sensitive.
  • Optional parameters may be used.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
Required parameters
Parameter Description
baseURL
string
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.
resourceType
string
The type of the requested resource.
Values:
  • style
  • sprite
  • glyph
resourceVersion
string
The version of the requested resource. If the version string contains a wildcard, the latest matching version of the resource will be provided. Available versions can be listed using the Metadata method.
Values:
  • A version.
  • A partial version ending with a wildcard character, e.g., *, 20.*, 20.0.2-*.
resourceName
string
The requested resource name (with an extension if applicable). Available resources can be listed using the Metadata method.
Value: A resource name.
key
string
Authorization key for access to the API.
Value: Your valid API Key.
Optional parameters
Parameter Description
resourceVariant
string
The variant of the requested resource. Available variants can be listed using the Metadata method.
Value: For example, tomtom

▲ Return to top

Merged style method

HTTPS method: GET

URL format

For ease of viewing and identification:

  • Required parameters are shown in bold text.
  • Optional parameters are shown in normal text.

The generic URL format is as follows:

http://baseURL/style/versionNumber/style/resourceVersion?key=Your_API_Key&map=map_style&traffic_incidents=traffic_incident_style&traffic_flow=traffic_flow_style

Examples

http://api.tomtom.com/style/1/style/20.3.2-3?key=Your_API_Key&map=basic_main&traffic_incidents=incidents_night&traffic_flow=flow_absolute
http://api.tomtom.com/style/1/style/20.3.2-3?key=Your_API_Key&map=basic_night&traffic_incidents=incidents_night
http://api.tomtom.com/style/1/style/20.3.2-3?key=Your_API_Key&traffic_incidents=incidents_s0&traffic_flow=flow_relative0

curl command

curl 'http://api.tomtom.com/style/1/style/20.3.2-3?key=Your_API_Key&traffic_incidents=incidents_s0&traffic_flow=flow_relative0'

Request parameters (Merged style method)

The following table describes the parameters that can be used in a Request.

  • Required parameters must be used or the call will fail.
  • Parameters and values are case-sensitive.
  • At least one of the optional parameters must be used or the call will fail.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
Required parameters
Parameter Description
baseURL
string
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.
resourceVersion
string
Version of the requested resource. Must be newer than or equal to 20.3.2-3. If the version string contains a wildcard, the latest matching version of the resource will be provided.
Values:
  • A version.
  • A partial version ending with a wildcard character, e.g., *, 20.*, 20.3.2-*.
key
string
The authorization key for access to the API.
Value: Your valid API Key.
Optional parameters
Parameter Description
map
string
Map style name to be used for merged style.
Values: See available map styles.
traffic_incidents
string
Traffic incidents style name to be used for merged style.
Values: See available incidents styles.
traffic_flow
string
Traffic flow style name to be used for merged style.
Values: See available flow styles.
Available styles
Name Available since Available until
Map styles
basic_main 20.3.2-3 -
basic_night 20.3.2-3 -
basic_main-lite 20.3.2-3 -
basic_night-lite 20.3.2-3 -
hybrid_main 20.3.2-3 -
hybrid_night 20.3.2-3 -
hybrid_main-lite 20.3.2-3 -
hybrid_night-lite 20.3.2-3 -
labels_main 20.3.2-3 -
labels_night 20.3.2-3 -
labels_main-lite 20.3.2-3 -
labels_night-lite 20.3.2-3 -
Incidents styles
incidents_day 20.3.2-3 -
incidents_dark 20.3.2-3 -
incidents_night 20.3.2-3 -
incidents_s0 20.3.2-3 -
incidents_s0-dark 20.3.2-3 -
incidents_s1 20.3.2-3 -
incidents_s2 20.3.2-3 -
incidents_s3 20.3.2-3 -
Flow styles
flow_absolute 20.3.2-3 -
flow_reduced-sensitivity 20.3.2-3 -
flow_relative-delay 20.3.2-3 -
flow_relative0 20.3.2-3 -
flow_relative0-dark 20.3.2-3 -

▲ Return to top

Merged sprite method

HTTPS method: GET

URL format

For ease of viewing and identification:

  • Required parameters are shown in bold text.
  • Optional parameters are shown in normal text.

The generic URL format is as follows:

http|https://baseURL/style/versionNumber/sprite/resourceVersion/type?key=Your_API_Key&map=map_style&traffic_incidents=traffic_incident_style&traffic_flow=traffic_flow_style

Examples

http://api.tomtom.com/style/1/sprite/20.3.2-3/sprite.png?key=Your_API_Key&map=basic_main&traffic_incidents=incidents_s0&traffic_flow=flow_relative0
http://api.tomtom.com/style/1/sprite/20.3.2-3/sprite@2x.json?key=Your_API_Key&map=basic_night&traffic_incidents=incidents_s0-dark
http://api.tomtom.com/style/1/sprite/20.3.2-3/sprite@2x.png?key=Your_API_Key&traffic_incidents=incidents_s1&traffic_flow=flow_relative0-dark

curl command

curl 'http://api.tomtom.com/style/1/sprite/20.3.2-3/sprite.json?key=Your_API_Key&traffic_incidents=incidents_s1&traffic_flow=flow_relative0-dark'

Request parameters (Merged sprite method)

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Parameters and values are case-sensitive.
  • At least one of the optional parameters must be used or the call will fail.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
Required parameters
Parameter Description
baseURL
string
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.
resourceVersion
string
Version of the requested resource. Must be newer than or equal to 20.3.2-3. If the version string contains a wildcard, the latest matching version of the resource will be provided.
Values:
  • A version.
  • A partial version ending with a wildcard character, e.g., *, 20.*, 20.3.2-*.
type
string
The requested type of data.
Values:
  • sprite.png
  • sprite@2x.png
  • sprite.json
  • sprite@2x.json
key
string
The authorization key for access to the API.
Value: Your valid API Key.
Optional parameters
Parameter Description
map
string
Map style name to be used for merged sprite.
Values: See available map styles.
traffic_incidents
string
Traffic incidents style name to be used for merged sprite.
Values: See available incidents styles.
traffic_flow
string
Traffic flow style name to be used for merged sprite.
Values: See available flow styles.
Available styles
Name Available since Available until
Map styles
basic_main 20.3.2-3 -
basic_night 20.3.2-3 -
basic_main-lite 20.3.2-3 -
basic_night-lite 20.3.2-3 -
hybrid_main 20.3.2-3 -
hybrid_night 20.3.2-3 -
hybrid_main-lite 20.3.2-3 -
hybrid_night-lite 20.3.2-3 -
labels_main 20.3.2-3 -
labels_night 20.3.2-3 -
labels_main-lite 20.3.2-3 -
labels_night-lite 20.3.2-3 -
Incidents styles
incidents_day 20.3.2-3 -
incidents_dark 20.3.2-3 -
incidents_s0 20.3.2-3 -
incidents_s0-dark 20.3.2-3 -
incidents_s1 20.3.2-3 -
Flow styles
flow_relative0 20.3.2-3 -
flow_relative0-dark 20.3.2-3 -

▲ Return to top

Host name cycling

Most web browsers have a default limitation on the number of active connections that can be allowed to each host.

  • This means if map tiles are being loaded via the api.tomtom.com host name, they will be loaded one at a time.
  • A trick that can be used to get around this limitation is to cycle through the hosts we have created as aliases.
  • These host names are:
    • a.api.tomtom.com
    • b.api.tomtom.com
    • c.api.tomtom.com
    • d.api.tomtom.com
  • By cycling through these four different host names, the web browser will be tricked into retrieving four map resources at a time rather than just one.
  • This will significantly speed up the performance of map loading.

For instance, if four map glyphs are being requested, you would request the first one as:

http://a.api.tomtom.com/map/1/glyph/(further parameters)

The second would be:

http://b.api.tomtom.com/map/1/glyph/(further parameters)

The third would be:

http://c.api.tomtom.com/map/1/glyph/(further parameters)

The fourth would be:

http://d.api.tomtom.com/map/1/glyph/(further parameters)

When more than four glyphs are being requested, start back again at a.api.tomtom.com.

▲ Return to top

Response data

Metadata method

The Response to a successful call will be the list of requested resources as shown in the following JSON Response code example. Exception responses will use the response codes described in the following Http Response Codes section.

Response body (JSON)

{
  "content" : [
    {
      "name" : "basic_main-lite.json",
      "type" : "resource"
    },
    {
      "name" : "basic_main.json",
      "type" : "resource"
    },
    {
      "name" : "basic_night-lite.json",
      "type" : "resource"
    },
    {
      "name" : "basic_night.json",
      "type" : "resource"
    },
    {
      "name" : "hybrid_main-lite.json",
      "type" : "resource"
    },
    {
      "name" : "hybrid_main.json",
      "type" : "resource"
    },
    {
      "name" : "hybrid_night-lite.json",
      "type" : "resource"
    },
    {
      "name" : "hybrid_night.json",
      "type" : "resource"
    },
    {
      "name" : "labels_main-lite.json",
      "type" : "resource"
    },
    {
      "name" : "labels_main.json",
      "type" : "resource"
    },
    {
      "name" : "labels_night-lite.json",
      "type" : "resource"
    },
    {
      "name" : "labels_night.json",
      "type" : "resource"
    }
  ]
}

Resource method

The Response to a successful Request will be the requested resource (style, glyph, or sprite). Exception responses will use the response codes described in the following Http Response Codes section.

Merged style method

The Response to a successful Request will be the merged style returned in JSON format. Exception responses will use the response codes described in the following Http Response Codes section.

Merged sprite method

The Response to a successful Request will be the merged sprite returned in PNG or JSON format depending on the passed format parameter. Exception responses will use the response codes described in the following Http Response Codes section.

HTTP Response codes

Code Meaning and Possible Causes
200 OK
400 Bad request: Received by the interface, but there is an exception while processing it. Possible causes include:
  • One or more of the required parameters are missing.
  • An unsupported or unrecognized parameter value.
This code is returned if the parameters of the Request were malformed. A detailed exception explanation is returned in the Response in the "form of service exception" report.
403 Forbidden: The supplied API Key is not valid for this Request.
404 Not found: The requested resource could not be found.
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 service.

▲ Return to top