TomTom LogoDocs
Products
Resources
Pricing
Sign in
Traffic API
Documentation
API Explorer

Raster Incident Tiles

Service version: 2Last edit: 2026.03.11TomTom Orbis Maps

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.

Styles description

Style details

NameMagnitude valuesLine outline colorsLine main colors
light

  • unknown

  • minor

  • moderate

  • major

  • undefined (road closures, indefinite delays etc.)

  • #7293a1

  • #aa830e

  • #941f0a

  • #570000

  • #ad0000

  • #e0e8eb

  • #ffc105

  • #fb2d09

  • #ad0000

  • #eff4f6

NameMagnitude valuesLine outline colorsLine main colors
dark

  • unknown

  • minor

  • moderate

  • major

  • undefined (road closures, indefinite delays etc.)

  • #626c6f

  • #8e620b

  • #811b09

  • #470000

  • #8f0000

  • #a9b0b2

  • #db9200

  • #e22503

  • #8f0000

  • #c6d0d2

Style examples

Example of light style

light example

Example of dark style

dark example

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}/maps/orbis/traffic/incidents/raster/tile/{zoom}/{x}/{y}?apiVersion=2&key={Your_API_Key}&style={style}

Example

get
Request URL example
https://api.tomtom.com/maps/orbis/traffic/incidents/raster/tile/12/2044/1360?apiVersion=2&key={Your_API_Key}&style=light

curl command format

get
Request curl command
curl 'https://{baseURL}/maps/orbis/traffic/incidents/raster/tile/{zoom}/{x}/{y}?apiVersion=2&style={style}' -H "TomTom-Api-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 parametersDescription

baseURL
string

The base URL for calling TomTom services. Value: api.tomtom.com

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..2zoom -1

y
integer

The y coordinate of the tile on the zoom grid.
Value: 0..2zoom -1

key
string

An API Key valid for the requested service.
Please note that using the TomTom-Api-Key header is recommended over the key query parameter for improved security.
Value: Your valid API Key.
Optional parametersDescription

style
string

The style to be used to render the tile.
Values:

  • light

  • dark

tileSize
integer

The tile size dimension in pixels.
Values: 256, and 512
Default value: 256

apiVersion
integer

Contains a version of the API to call. Value: The current version is 2.

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.

Required headersDescription
TomTom-Api-Key

An API Key valid for the requested service.
Preferred method for authentication. Using the header is recommended over the key query parameter for improved security.
Value: Your valid API Key.

TomTom-Api-Version

Contains a version of the API to call.
Value: An integer; the current version is 2.
Optional headersDescription
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 response format. If the preferred format is not supported, the server will fall back to the default one.
Value: Accept: image/png

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>

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 JSON format.

Error response field structure

FieldDescription

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 - JSON
{
  "detailedError": {
    "code": "INVALID_REQUEST",
    "message": "z out of range 0 &lt;= z &lt;= 22"
  }
}

Response codes

CodeMeaning & 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,2zoom -1]: The requested x coordinate is out of the possible range.

  • y n is out of range [0,2zoom -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.

HeaderDescription
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 code is returned.
Value: GET, HEAD

Cache-Control

Contains directives for a caching mechanism.

Value: max-age=<number>

Content-Length

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

Content-Type

Indicates the media type of the resource returned.
Values:

  • image/png - in case of the 200 OK

  • application/json; charset=utf-8 - in case of the 400 Bad Request

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>