Sorry, you need to enable JavaScript to visit this website.
Market Coverage
Traffic API
Get your key

Raster Flow Tiles

 

Service version: 4
Last edit: 2021.07.20

On this page

Purpose

The TomTom Traffic Raster Flow Tile service serves 256 x 256 pixel or 512 x 512 pixel tiles showing traffic flow.

  • 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.
  • The Raster Flow tiles use colors to indicate either the speed of traffic on different road segments, or the difference between that speed and the free-flow speed on the road segment in question.

Run this endpoint

You can easily run this and other endpoints.

  1. Go to the TomTom API Explorer page.
  2. Click an endpoint.
    1. Click Try it out.
    2. Enter/select all required parameter values and any optional parameter values.
    3. At the bottom of the form, click Execute.
  3. Review the Response.

Styles description

Style details
Name Relation to speed Speed intervals Line outline colors Line main colors Dash colors
absolute absolute
  • 0 ≤ speed < 1
  • 1 ≤ speed < 60
  • 60 ≤ speed < 120
  • 120 ≤ speed
  • #3C3C3C
  • #801212
  • #80801C
  • #166416
  • #777777
  • #FF2323
  • #FFFF37
  • #2BC82B
No dashes
relative relative to free-flow
  • 0 ≤ speed < 0.01
  • 0.01 ≤ speed < 0.8
  • 0.8 ≤ speed < 1
  • speed = 1
  • #3C3C3C
  • #801212
  • #80801C
  • #166416
  • #777777
  • #FF2323
  • #FFFF37
  • #2BC82B
No dashes
relative0 relative to free-flow
  • road closed
  • 0 ≤ speed < 0.15
  • 0.15 ≤ speed < 0.35
  • 0.35 ≤ speed < 0.75
  • 0.75 ≤ speed
  • #666666
  • #A50704
  • #DF4B15
  • #E87B3D
  • #245723
  • #C1272D
  • #E70704
  • #F18237
  • #F1BF40
  • #2EAB30
  • #F2F2F2
  • #CC0704
  • #EC6736
  • #F1A828
  • No dashes
relative0-dark relative to free-flow
  • road closed
  • 0 ≤ speed < 0.15
  • 0.15 ≤ speed < 0.35
  • 0.35 ≤ speed < 0.75
  • 0.75 ≤ speed
  • #474747
  • #730402
  • #9B340E
  • #A2562A
  • #193C18
  • #861B1F
  • #A10402
  • #A85A26
  • #A9862C
  • #207721
  • #A8A8A8
  • #8E0402
  • #A54825
  • #A9751C
  • No dashes
relative-delay relative to free-flow
  • 0 ≤ speed < 0.01
  • 0.01 ≤ speed < 0.8
  • 0.08 ≤ speed < 1
  • speed = 1
  • #3C3C3C
  • #801212
  • #80801C
  • #166416
  • #777777
  • #FF2323
  • #FFFF37
  • #2BC82B
No dashes
reduced-sensitivity relative to free-flow
  • 0 ≤ speed < 0.01
  • 0.01 ≤ speed < 0.53
  • 0.53 ≤ speed < 0.67
  • 0.67 ≤ speed
  • #3C3C3C
  • #801212
  • #80801C
  • #166416
  • #777777
  • #FF2323
  • #FFFF37
  • #2BC82B
No dashes

Style examples

Example of relative0 style

relative0 example

Example of relative0-dark style

relative0-dark example

▲ Return to top

Request data

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.
https://baseURL/traffic/map/versionNumber/tile/flow/style/zoom/x/y.format?key=Your_API_Key&thickness=thickness

Example

https://api.tomtom.com/traffic/map/4/tile/flow/absolute/12/2044/1360.png?key=Your_API_Key

curl command

curl 'https://baseURL/traffic/map/versionNumber/tile/flow/style/zoom/x/y.format?key=Your_API_Key&thickness=thickness'

▲ Return to top

Request parameters

The following table describes all of 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
Parameter Description
baseURL
string		 Base URL for calling TomTom services.
Value: api.tomtom.com
versionNumber
string		 Version of the service to call.
Value: The current value is 4.
style
string		 The style to be used to render the tile.
  • When the style is absolute, the colors will reflect the absolute speed measured.
  • Calls using the relative, relative0 and relative0-dark styles return the speed relative to free-flow, highlighting areas of congestion.
  • Style relative-delay displays relative speeds only where they are different from the free-flow speeds.
  • Style reduced-sensitivity displays relative speeds but larger difference from free-flow (depending on FRC) is required for segment to change the color.
  • Styles relative0 and relative0-dark are recommended to use.
Value:
  • absolute
  • relative
  • relative0
  • relative0-dark
  • relative-delay
  • reduced-sensitivity
zoom
integer		 Zoom level of the tile to be rendered.
Value: 0..22
x
integer		 x coordinate of the tile on the zoom grid.
Value: 0..2 zoom -1
y
integer		 y coordinate of tile on zoom grid.
Value: 0..2 zoom -1
format
string		 The format of the response.
Value: png
apiKey
string		 API Key valid for requested service.
Value: Your valid API Key.
Optional parameters
Parameter Description
[thickness]
integer		 The segment width multiplier.
This parameter can only be used with the following styles:
  • absolute
  • relative
  • relative-delay
  • reduced-sensitivity
Value: 1..20
Default value: 10
[tileSize]
integer		 The tile size dimension in pixels.
Value:
  • 256
  • 512
Default value: 256

Note that the flow layer can create a patchwork tile effect if the flow traffic data changes between calls of adjacent tiles.

▲ Return to top

HTTP request headers

The following table lists HTTP request headers of particular interest to clients of the Raster Flow Tiles API endpoint.

Required headers
There are no required headers in this endpoint.
Optional headers
Parameter 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/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

▲ Return to top

Response data

Successful response

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

Error response

The Raster Flow 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 an 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 XML example

<errorResponse errorCode="400" description="z out of range 0 <= z <= 22" version="traffic-rasterizer 2.0.009">
  <detailedError>
    <code>INVALID_REQUEST</code>
    <message>z out of range 0 <= z <= 22</message>
  </detailedError>
</errorResponse>

Error response JSON example

{
  "detailedError" : {
    "code" : "INVALID_REQUEST",
    "message" : "z out of range 0 <= z <= 22"
  }
}

▲ Return to top

HTTP response codes

Code Meaning & possible causes
200 OK
400 Bad request
  • Unknown style: The requested style is not available.
  • 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 format: The requested format is not supported.
  • Invalid thickness parameter value.
  • Invalid combination of the style and thickness parameter.
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.

▲ Return to top

HTTP response headers

The following table lists HTTP response headers of particular interest to clients of the Raster Flow 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 Code 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/png - in case of the 200 OK
  • application/json; charset=utf-8 - in case of the 400 Bad Request
  • text/xml; 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>

▲ Return to top