Raster Incident Tiles

Service version: 4

Last edit: 2022.09.12

Purpose

The TomTom Traffic Tile service serves 256 x 256 pixel or 512 x 512 pixel tiles showing traffic incidents. All tiles use the same grid system. Because the traffic tiles use transparent images, they can be layered on top of map tiles to create a compound display. Traffic tiles render graphics to indicate traffic on the roads in the specified area. The Traffic incidents tiles use colors to indicate the magnitude of delay associated with the particular incident on a road segment. The magnitude of delay is determined based on the severity of traffic congestion associated with the particular incident.

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

Styles description

Style details

Name	Magnitude values	Line glow colors	Line outline colors	Line main colors	Dash colors	POI stroke colors	POI main colors
`s0`	`0`: Unknown `1`: Minor `2`: Moderate `3`: Major `4`: Undefined (road closures, indefinite delays etc.)	No glow	`#0000004C` `#F58240` `#EB4C13` `#AB0000` `#666666`	`#0000004C` `#FFCE43` `#FF8939` `#F40000` `#C1272D`	`#FFFFFF4C` `#FFB429` `#FA6C38` `#D60000` `#F2F2F2`	`#FFFFFF` `#F58240` `#EB4C13` `#AB0000` `#F2F2F2`	`#B2B2B2` `#FFCE43` `#FF8939` `#F40000` `#C1272D`
Name	Magnitude values	Line glow colors	Line outline colors	Line main colors	Dash colors	POI stroke colors	POI main colors
`s0-dark`	`0`: Unknown `1`: Minor `2`: Moderate `3`: Major `4`: Undefined (road closures, indefinite delays etc.)	No glow	`#0000004C` `#A2562A` `#9B340E` `#730402` `#474747`	`#0000004C` `#A9862C` `#A85A26` `#A10402` `#861B1F`	`#FFFFFF4C` `#A9751C` `#A54825` `#8E0402` `#A8A8A8`	`#B3B3B3` `#A2562A` `#9B340E` `#730402` `#A8A8A8`	`#7B7B7B` `#A9862C` `#A85A26` `#A10402` `#861B1F`
Name	Magnitude values	Line glow colors	Line outline colors	Line main colors	Dash colors	POI stroke colors	POI main colors
`s1`	`0`: Unknown `1`: Minor `2`: Moderate `3`: Major `4`: Undefined (road closures, indefinite delays etc.)	No glow	`#383838` `#383838` `#383838` `#383838` `#383838`	`#FFFFFF` `#FFFFFF` `#FFFFFF` `#FFFFFF` `#FFFFFF`	`#BFBFBF` `#FFA236` `#FF151C` `#BE0F13` `#BFBFBF`	No POIs	No POIs
Name	Magnitude values	Line glow colors	Line outline colors	Line main colors	Dash colors	POI stroke colors	POI main colors
`s2`	`0`: Unknown `1`: Minor `2`: Moderate `3`: Major `4`: Undefined (road closures, indefinite delays etc.)	`#FFC830` `#FFA236` `#FB0000` `#AE0000` `#FFC830`	`#505050` `#505050` `#202020` `#202020` `#505050`	`#BFBFBF` `#FFA236` `#FB0000` `#AE0000` `#BFBFBF`	No dashes	No POIs	No POIs
Name	Magnitude values	Line glow colors	Line outline colors	Line main colors	Dash colors	POI stroke colors	POI main colors
`s3`	`0`: Unknown `1`: Minor `2`: Moderate `3`: Major `4`: Undefined (road closures, indefinite delays etc.)	`#FFC830` `#FFA236` `#FB0000` `#AE0000` `#FFC830`	`#505050` `#505050` `#202020` `#202020` `#505050`	`#BFBFBF` `#FFA236` `#FB0000` `#AE0000` `#BFBFBF`	No dashes	No POIs	No POIs
Name	Magnitude values	Line glow colors	Line outline colors	Line main colors	Dash colors	POI stroke colors	POI main colors
`night`	`0`: Unknown `1`: Minor `2`: Moderate `3`: Major `4`: Undefined (road closures, indefinite delays etc.)	`#8B837D` `#8B837D` `#8B837D` `#8B837D` `#8B837D`	`#8B837D` `#FFA236` `#FB0000` `#AE0000` `#AE0000`	`#8B837D` `#FFA236` `#FB0000` `#AE0000` `#FFFFFF`	No dashes	No POIs	No POIs

Style examples

Example of `s0` style

Example of `s0-dark` style

Request data

HTTPS method: `GET`

Constants and parameters enclosed in curly brackets { } must be replaced with their values.
Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

URL format

get

Request URL format

https://{baseURL}/traffic/map/{versionNumber}/tile/incidents/{style}/{zoom}/{x}/{y}.{format}?key={Your_API_Key}&t={t}

Example

get

Request URL example

https://api.tomtom.com/traffic/map/4/tile/incidents/s3/12/2044/1360.png?key={Your_API_Key}

curl command format

get

Request curl command

curl 'https://api.tomtom.com/traffic/map/4/tile/incidents/s3/12/2044/1360.png?key={Your_API_Key}'

Request parameters

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	The base URL for calling TomTom services. Values: `api.tomtom.com`: The default global API endpoint. `kr-api.tomtom.com`: The region-specific endpoint for South Korea. See the region-specific content documentation.
`versionNumber` string	The version of the service to call. Value: The current value is `4`.
`style` string	The style to be used to render the tile. `s0` and `s0-dark` create traffic lines with different color intensities and colored chevrons indicating the severity. `s1` creates traffic lines with colored chevrons indicating the severity. `s2` and `s3` create plain lines with different degrees of glow. `night` does not group incidents into clusters. Styles `s0` and `s0-dark` are recommended to use. Values: `s0` `s0-dark` `s1` `s2` `s3` `night`
`zoom` integer	The zoom level of the tile to be rendered. Value: `0..22`
`x` integer	The `x` coordinate of the tile on the zoom grid. Value: 0..2 ^zoom -1
`y` integer	The `y` coordinate of the tile on the zoom grid. Value: 0..2 ^zoom -1
`key` string	An API Key valid for the requested service. Value: Your valid `API Key`.
`format` string	The format of the response. Value: `png` `gif`

Optional parameters	Description
`t` string	The Traffic Model ID is the reference value for the state of traffic at a particular time. Use `-1` to get the most recent traffic information. Default value: `-1`
`tileSize` integer	The tile size dimension in pixels. Values: `256`, and `512` Default value: `256`

Request headers

The following table lists HTTP response headers of particular interest to clients of the Traffic Incident Raster Tiles API endpoint. Note: There are no required headers in this endpoint.

Optional headers	Description
Tracking-ID	Specifies an identifier for the request. It can be used to trace a call. The value must match the regular expression `'^[a-zA-Z0-9-]{1,100}$'`. An example of the format that matches this regular expression is a UUID (e.g., `9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1` ). For details check RFC 4122. If specified, it is replicated in the Tracking-ID response header. It is only meant to be used for support and does not involve tracking of you or your users in any form. Value: `<string>`
Accept	Advertises which content types, expressed as MIME types, the client is able to understand. In this service, the header is used to specify a preferred Bad Request response format. Format: `Accept: type/subtype` `Accept: type/subtype, type/subtype` - for multiple types Value `type/subtype` is one of: `image/gif` - in case of the `200 OK` `image/png` - in case of the `200 OK` `application/json` - in case of the `400 Bad Request` `text/xml` - in case of the `400 Bad Request` Examples: `Accept: application/json` `Accept: image/png, application/json`

Optional headers

Description

Tracking-ID

Specifies an identifier for the request. It can be used to trace a call. The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'. An example of the format that matches this regular expression is a UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1 ). For details check RFC 4122. If specified, it is replicated in the Tracking-ID response header. It is only meant to be used for support and does not involve tracking of you or your users in any form.
Value: <string>

Advertises which content types, expressed as MIME types, the client is able to understand. In this service, the header is used to specify a preferred Bad Request response format.
Format:

Accept: type/subtype
Accept: type/subtype, type/subtype - for multiple types

Value type/subtype is one of:

image/gif - in case of the 200 OK
image/png - in case of the 200 OK
application/json - in case of the 400 Bad Request
text/xml - in case of the 400 Bad Request

Examples:

Accept: application/json
Accept: image/png, application/json

Response data

Successful response

The Raster Incident Tiles API endpoint for a valid single request returns a response in PNG format. See: style examples for more information.

Error response

The Raster Incident Tiles API endpoint for an invalid single request returns a response body in XML or JSON format. By default the Error response is returned in XML format. In order to obtain the Error response in JSON format, the Accept request header with a proper value must be used. The types of the fields refer to a JSON response.

Error response field structure

Field	Description
`detailedError` object	Main object of the error response.
`code` string	One of a server-defined set of error codes.
`message` string	A human-readable description of the error code.

Error response example - XML
1<errorResponse errorCode="400" description="z out of range 0 <= z <= 22" version="traffic-rasterizer 2.0.009">
2  <detailedError>
3    <code>INVALID_REQUEST</code>
4    <message>z out of range 0 <= z <= 22</message>
5  </detailedError>
6</errorResponse>

Error response example - JSON
1{
2  "detailedError": {
3    "code": "INVALID_REQUEST",
4    "message": "z out of range 0 &lt;= z &lt;= 22"
5  }
6}

Response codes

Code	Meaning & possible causes
`200`	OK
`400`	Bad request, usually due to a malformed syntax. Zoom n is out of range [0,22]: The requested zoom level is out of the possible range. x n is out of range [0,2 zoom -1]: The requested x coordinate is out of the possible range. y n is out of range [0,2 zoom -1]: The requested y coordinate is out of the possible range. *Unknown Content Type: nnn:* The requested content type is not supported.
`403`	Forbidden: The supplied API Key is not valid for this request.
`405`	Method Not Allowed: The provided HTTP request method is known by the server, but is not supported by the target resource.
`429`	Too Many Requests: Too many requests were sent in a given amount of time for the supplied API Key.
`500`	Internal Server Error
`503`	Service currently unavailable
`596`	Service Not Found: Unknown version of the service

Response headers

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

Header	Description
Access-Control-Allow-Origin	Indicates that cross-origin resource sharing (CORS) is allowed. Value: `*`
Allow	Lists the set of supported HTTP methods. The header is sent in case a `405` HTTP response Ccde is returned. Value: `GET`, `HEAD`
Cache-Control	Contains directives for a caching mechanism. Value: `private`, `no-cache`, `no-store`, `max-age=0`, `must-revalidate`
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: `image/gif` `image/png` `application/json; charset=utf-8` - in case of the `400 Bad Request` `text/xml; charset=utf-8` - in case of the `400 Bad Request` In case of the `200 OK` the response content should be interpreted according to the type of the `format` request parameter.
Date	Contains the date and time when the message was originated. Value: `<http-date>`
Tracking-ID	An identifier for the request. If the Tracking-ID header was specified in the request, it is replicated in the response. Otherwise, it is generated automatically by the service. For details check RFC 4122. It is only meant to be used for support and does not involve tracking of you or your users in any form. Value: `<string>`
TrafficModelID	Contains the reference value for the state of traffic at a particular time. If the request contains a valid Traffic Model ID and is not equal to `-1`, its value is replicated here. If the request does not contain a Traffic Model ID or it is equal to `-1`, the most recent one is returned. Value: `<numeric>`