Map Styles v2

Service version: 4
Last edit: 2024.09.19

Public Preview Notice

This API is in Public Preview. Go to the Public Preview - what is it? page to see what this means.

Purpose

The Traffic API Resource service delivers resources required to display vector traffic 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.

Request data

Metadata method

HTTPS method: GET

Please see the following Request parameters section with the required and optional parameters tables for these values. The generic URL format is as follows.

URL format

get
Request URL
https://{baseURL}/traffic/map/{versionNumber}/{resourceType}/{resourceVersion}/{resourceVariant}/metadata.{format}?key={Your_API_Key}

Examples

get
Request URL examples
1https://api.tomtom.com/traffic/map/4/style/metadata.json?key={Your_API_Key}
2
3https://api.tomtom.com/traffic/map/4/sprite/22.2.1-9/metadata.json?key={Your_API_Key}
4
5https://api.tomtom.com/traffic/map/4/glyph/22.2.1-9/metadata.json?key={Your_API_Key}

curl command format

get
Request curl command
curl 'https://api.tomtom.com/traffic/map/4/sprite/22.2.1-9/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.

Required parameters

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

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

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., *, 22.*, 22.2.1-*.

resourceVariant
string

Variant of the requested resource. Can only be used when resourceVersion is provided.
Value: The variant name, e.g., 2

Resource method

HTTPS method: GET

Please see the following Request parameters section with the required and optional parameters tables for these values. The generic URL format is as follows.

URL format

get
Request URL
https://{baseURL}/traffic/map/{versionNumber}/{resourceType}/{resourceVersion}/{resourceVariant}/{resourceName}?key={Your_API_Key}

Example

get
Request example
1https://api.tomtom.com/traffic/map/4/style/22.*/2/incidents_light.json?key={Your_API_Key}
2
3https://api.tomtom.com/traffic/map/4/style/22.2.1-9/2/incidents_light.json?key={Your_API_Key}
4
5https://api.tomtom.com/traffic/map/4/sprite/22.2.1-9/2/incidents_light/sprite.png?key={Your_API_Key}

curl command format

get
Request curl command
curl 'https://api.tomtom.com/traffic/map/4/style/22.2.1-9/2/incidents_light.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.

Required parameters

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

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., *, 22.*, 22.2.1-*.

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

Description

resourceVariant
string

The variant of the requested resource. Available variants can be listed using the Metadata method.
Value: For example, 2

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 styles are being requested, you would request the first one as:

get
Request URL using a.api.tomtom.com
https://a.api.tomtom.com/traffic/map/4/style/(further parameters)

The second would be:

get
Request URL using b.api.tomtom.com
https://b.api.tomtom.com/traffic/map/4/style/(further parameters)

The third would be:

get
Request URL using c.api.tomtom.com
https://c.api.tomtom.com/traffic/map/4/style/(further parameters)

The fourth would be:

get
Request URL using d.api.tomtom.com
https://d.api.tomtom.com/traffic/map/4/style/(further parameters)

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

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 Response codes.

Response body - Metadata method - JSON
1{
2 "content": [
3 {
4 "name": "2",
5 "type": "variant"
6 },
7 {
8 "name": "flow_absolute.json",
9 "type": "resource"
10 },
11 {
12 "name": "flow_reduced-sensitivity.json",
13 "type": "resource"
14 },
15 {
16 "name": "flow_relative-delay.json",
17 "type": "resource"
18 },
19 {
20 "name": "flow_relative.json",
21 "type": "resource"
22 },
23 {
24 "name": "flow_relative0-dark.json",
25 "type": "resource"
26 },
27 {
28 "name": "flow_relative0.json",
29 "type": "resource"
30 },
31 {
32 "name": "incidents_dark.json",
33 "type": "resource"
34 },
35 {
36 "name": "incidents_day.json",
37 "type": "resource"
38 },
39 {
40 "name": "incidents_night.json",
41 "type": "resource"
42 },
43 {
44 "name": "incidents_s0-dark.json",
45 "type": "resource"
46 },
47 {
48 "name": "incidents_s0.json",
49 "type": "resource"
50 },
51 {
52 "name": "incidents_s1.json",
53 "type": "resource"
54 },
55 {
56 "name": "incidents_s2.json",
57 "type": "resource"
58 },
59 {
60 "name": "incidents_s3.json",
61 "type": "resource"
62 }
63 ]
64}

Resource method

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

Response codes

Code

Meaning & 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.

A detailed exception explanation is returned in the response in the "form of a 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.

Response headers

The following table lists HTTP response headers of particular interest to clients of the Traffic Incident Details API endpoint.

Header

Description

Access-Control-Allow-Origin

Indicates that cross-origin resource sharing (CORS) is allowed.
Value: * universal.

Cache-Control

Contains directives for a caching mechanism.
Values: <public>, <no-cache>

Content-Length

Contains information about the size of the response body.
Value: <decimal number>

Content-Type

Indicates the media type of the resource returned.
Value: <application/json charset=utf-8>

Date

Contains the date and time when the message was originated.
Value: <http-date>

Content-Encoding

Indicates that gzip compression is supported.
Value: gzip

Style visual examples

Style namePreview

Example of the 2/flow_relative-light traffic flow style

2/flow_relative-light

Example of the 2/flow_relative-dark traffic flow style

2/flow_relative-dark

Example of the 2/incidents_light traffic incidents style

2/incidents_light

Example of the 2/incidents_dark traffic incidents style

2/incidents_dark

Example of the relative0 traffic flow style

relative0

Example of the relative0-dark traffic flow style

relative0-dark

Example of the s0 traffic incidents style

s0

Example of the s0-dark traffic incidents style

s0-dark

Example of the day traffic incidents style

day

Example of the dark traffic incidents style

dark