Map Styles
Service version: 4
Last edit: 2020.04.10
On this page
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
URL format
For ease of viewing and identification:
- Required constants and parameters are shown in bold text.
- Optional parameters are shown in plain text.
The generic URL format is as follows:
http|https://baseURL/traffic/map/versionNumber/resourceType/resourceVersion/resourceVariant/metadata.format?key=Your_API_Key
Examples
http://api.tomtom.com/traffic/map/4/style/metadata.xml?key=Your_API_Key
http://api.tomtom.com/traffic/map/4/sprite/20.2.4-0/metadata.json?key=Your_API_Key
http://api.tomtom.com/traffic/map/4/glyph/20.2.4-0/metadata.json?key=Your_API_Key
curl command
curl 'http://api.tomtom.com/traffic/map/4/sprite/20.2.4-0/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 4 .
|
resourceType string |
The type of the requested resource. Values:
|
format string |
The requested response format. Values:
|
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. Value: The resource version. |
resourceVariant string |
Variant of the requested resource. Can only be used when resourceVersion is provided. Value: The variant name. |
Resource method
HTTPS method: GET
URL format
For ease of viewing and identification:
- Required constants and parameters are shown in bold text.
- Optional parameters are shown in plain text.
The generic URL format is as follows:
http|https://baseURL/traffic/map/versionNumber/resourceType/resourceVersion/resourceVariant/resourceName?key=Your_API_Key
Example
http://api.tomtom.com/traffic/map/4/style/20.2.4-0/flow_absolute.json?key=Your_API_Key
curl command
curl 'http://api.tomtom.com/traffic/map/4/style/20.2.4-0/flow_absolute.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 4 .
|
resourceType string |
The type of the requested resource. Values:
|
resourceVersion string |
The version of the requested resource. Available versions can be listed using the Metadata method. Value: A resource version. |
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, flow_absolute
|
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:
http://a.api.tomtom.com/traffic/map/4/style/(further parameters)
The second would be:
http://b.api.tomtom.com/traffic/map/4/style/(further parameters)
The third would be:
http://c.api.tomtom.com/traffic/map/4/style/(further parameters)
The fourth would be:
http://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 HTTP Response codes section.
Response body (JSON)
{
"content" : [
{
"name" : "flow_absolute.json",
"type" : "resource"
},
{
"name" : "flow_reduced-sensitivity.json",
"type" : "resource"
},
{
"name" : "flow_relative.json",
"type" : "resource"
},
{
"name" : "flow_relative0-dark.json",
"type" : "resource"
},
{
"name" : "flow_relative0.json",
"type" : "resource"
},
{
"name" : "flow_relative-delay.json",
"type" : "resource"
},
{
"name" : "incidents_dark.json",
"type" : "resource"
},
{
"name" : "incidents_day.json",
"type" : "resource"
},
{
"name" : "incidents_night.json",
"type" : "resource"
},
{
"name" : "incidents_s0-dark.json",
"type" : "resource"
},
{
"name" : "incidents_s0.json",
"type" : "resource"
},
{
"name" : "incidents_s1.json",
"type" : "resource"
},
{
"name" : "incidents_s2.json",
"type" : "resource"
},
{
"name" : "incidents_s3.json",
"type" : "resource"
}
]
}
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.
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:
|
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. |
HTTP 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. Value: <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 at which the message was originated. Value: <http-date> |
Content-Encoding |
Indicates that gzip compression is supported. Value: gzip
|