Traffic Flow - Protobuf

Last edit: 2025.03.12
TomTom Maps

Purpose

The TomTom Traffic Flow - Intermediate Service - Protobuf (hereafter called 'Service') is designed for server-to-server integration with traffic control center, routing, navigation, and mapping applications. It contains real-time travel times and speeds for segments, based on TomTom's Traffic technology, with several possible configurations.

This document describes the data exchange method and the payload description of the Service interface. Be aware that the 'Service' is available in three variations:

  1. TomTom Traffic Flow (Standard feed)
  2. TomTom Traffic Flow Detailed (higher road coverage) and
  3. TomTom Traffic Flow Detailed Legacy (higher road coverage, shorter links, no dynamic sectioning)

See more details on differences between Flow and Flow Detailed in the FAQ.

Scope

This document gives basic information on the Service and shows how to configure it to work with your environment. The user is expected to have basic installation knowledge and experience using protocol buffers.

Intended audience

This document is intended to be used by TomTom partners and customers (decision makers and developers).

Features

TomTom offers traffic flow data to customers. A custom product is configured based upon your specific needs. The product is static, so included regions and features are fixed (once the product is configured), it contains standard configuration (see section Default enabled information) but it also provides customizable configuration options (see section Optionally activatable features).

Request data

The Service uses RESTful API (Representation State Transfer) technology. Since you only need to use one URL, the Service is relatively uncomplicated to use. To make a request, the URL is constructed as shown in the following sections.

Important

To use this Service, ensure that all prerequisites are met as described in the section A secure connection or at Authentication for client certificate access.

HTTPS Method: GET

For ease of viewing and identification:

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

The sample URL is formatted in one of two possible ways:

TomTom Traffic Flow

get
URL format
https://{baseURL}/tsq/hdf/{productName}/{apiKey}/content.proto[?flowType={flowType}]

The following is an example URL:

get
URL example
https://cert-traffic.tomtom.com/tsq/hdf/DEU-OPENLR/{Your_API_Key}/content.proto

The following is an example cURL request:

get
cURL request example
curl --compressed -XGET 'https://cert-traffic.tomtom.com/tsq/hdf/DEU-OPENLR/{Your_API_Key}/content.proto'

TomTom Traffic Flow Detailed / TomTom Traffic Flow Detailed Legacy

get
URL format
https://{baseURL}/tsq/hdf-detailed/{productName}/{apiKey}/content.proto[?flowType={flowType}]

The following is an example URL request:

get
URL example
https://cert-traffic.tomtom.com/tsq/hdf-detailed/DEU-OPENLR/{Your_API_Key}/content.proto

The following is an example cURL request:

get
cURL request example
curl --compressed -XGET 'https://cert-traffic.tomtom.com/tsq/hdf-detailed/DEU-OPENLR/{Your_API_Key}/content.proto'

Request parameters

The following table provides a detailed explanation of the available fields that were previously shown.

Required parametersDescription

baseURL
string

Base URL for calling the API.
Value: cert-traffic.tomtom.com

productName
string

Name of the product (feed) you are requesting. These will be indicated to you as part of the provisioning process. Typically, it explains the country (country code), and the location referencing method (see Location referencing).
Examples: DEU-OPENLR, DEU-TMC

apiKey
string

Authorization key for access to the API.
Value: Your valid API key.

Optional parametersDescription

flowType
string

When the feed is requested without the parameter flowType it contains ALL messages covered by the feed. In that case, the field averageSpeed in a message represents the current speed for congested road segments and the free-flow speed for non-congested road segments. By using the flowType parameter, the response can be shaped to only support a certain speed type. This also affects the number of messages in the response. There are two values supported for this parameter:

  • ff, gets the messages for ALL road segments covered by the feed. The field averageSpeed in the message provides the free-flow speed for the affected road segment.

  • nff, only gets the messages for road segments that are NOT in a free-flow state. The field averageSpeed of a message provides the currently measured speed for the affected road segment.

When using this parameter, at the first request the free-flow information should be downloaded. Afterwards, non-free-flow information can be downloaded for each future request. The free-flow and non-free-flow data are related. The segments for both files should be in sync, otherwise there is a mismatch in the locations of the free-flow data. Therefore, every time the non-free-flow information is downloaded, it must be checked. This insures that the non-free-flow data corresponds to the free-flow data (that the user already has).

The verification is done by confirming the clientID within supplierAndClientInfo in protocol buffers format. If the clientID of the non-free-flow content does not match the clientID of the free-flow content that was downloaded with the first request, the free-flow information must be re-requested. See more details in the FAQ about speeds in non free flow feed page.
Values: flowType=nff, flowType=ff

Request headers

Since flow feeds can be very large, TomTom recommends optimizing the information transmission as much as possible. Through optimization, the client receives more up-to-date information.

All responses will be gzip compressed as it significantly reduces the payload size. The use of the HTTP header Accept-Encoding is required. For more information see our page about Gzip compression.

HeadersDescription
If-Modified-Since

TomTom recommends using the standard HTTP header If-Modified-Since with the last value of Last-Modified received. When this header is used properly, you avoid unnecessarily downloading identical content. For details, see the HTTP/1.1 standard (RFC2616 section 14.25).
Value: Example: Wed, 21 Oct 2015 07:28:00 GMT

Response data

Response codes

Response codeDescription
200 OK

Indicates that the request has succeeded. The response body will contain the requested data.

304 Not Modified

Only used if the If-Modified-Since header has been set by the client. Indicates that the requested data has not been modified since the last request. For more information see Request headers.

401 Unauthorized

Indicates that the request requires user authentication information. The client MAY repeat the request with a suitable Authorization header field.

406 Not Acceptable

The server doesn't find any content that conforms with the Accept-Encoding header sent in the request. This may happen if Accept-Encoding is set to identity or gzip;q=0 or if no Accept-Encoding header is present. If the Accept-Encoding header is not set or does not support gzip, the server will return a 406 status code with a message indicating the issue.

Response example

If you make the following request:

get
URL example
https://cert-traffic.tomtom.com/tsq/hdf-detailed/DEU-OPENLR/{Your_API_Key}/content.proto?flowType=nff

You can expect a response that contains protocol buffers binary data. The textual representation of this data could look like this:

1metaInformation {
2 createTimeUTCSeconds: 1452092910
3 supplierAndClientInfo {
4 clientID: "db14af1d-3827-4d61-8525-8f70bc1c5b3f15e87601"
5 supplierID: "TomTom Traffic Service"
6 }
7 }
8[...]
9trafficFlow {
10 location {
11 openlr: "\013\t\223\332%UF\033`\013\001)\002$\033S~"
12 }
13 speed {
14 averageSpeedKmph: 5
15 travelTimeSeconds: 334
16 confidence: 97
17 relativeSpeed: 0.106
18 trafficCondition: STATIONARY_TRAFFIC
19 }
20}
21[...]

Response - Protobuf payload specification (analysis of the received output)

Protocol buffers is the de-facto standard for encoding and transmitting any structured information in a compact, platform-independent way. TomTom uses protocol buffers (version 2) format for the output payload. After defining the data structure an encoder and a decoder can be generated for integration into C++, Java and several other languages. Also see http://code.google.com/p/protobuf or https://protobuf.dev for more information.

Important: Protocol buffers schema

Our output type uses the proprietary TomTom protocol buffers message types. The data structure of the protocol buffers output is defined in the schema file ProtobufTrafficFlow_v8.proto. TomTom supports schema version 8 and above.

All fields are marked as optional, as recommended by Google, but the output always contains flow information (including a location).

The following table contains a brief description of the supported message types used in the data structure. More detailed information about the individual message fields can be found in the following sections: some fields are filled in by default, other fields require a specific feature to be enabled with the product.

Protocol buffers message typeDescription
TrafficFlowGroup

The traffic flow group is the top-level message. It provides meta data (see MetaInformation) and the flow entries themselves, whereby TrafficFlowWithPredictionPerSection is used when the optional feature Flow prediction is activated and TrafficFlow otherwise.

MetaInformation

The meta information message provides data shared by all traffic flow messages.

SupplierAndClientInfo

The supplier and client information message identifies the client and the supplier.

TrafficFlow

The traffic flow message assigns speed information to a location. It may also identify road blockages.

TrafficFlowWithPrediction [deprecated]

The traffic flow message assigns current and future speed information to a location at several points in time. It may also identify road blockages. This message type is used with products configured for prediction and NOT for breaking up locations into sections.

TrafficFlowWithPredictionPerSection

This message assigns current and future speed information to sections of a location at several points in time.

Speed

The speed message subsumes all speed and travel time related information. Which fields are set depends on the customizable product configurations (see the section Optionally activatable features).

SectionSpeed

The SectionSpeed message provides speed information for the section of a location. The section is indicated by the offset of the starting point from the start point of the location. The ending offset is either the end of the location or the start of the next section, if there is a next section. SectionSpeed may also identify road blockages.

SpeedWithTimeStamp [deprecated]

SpeedWithTimeStamp gives speed information details at a point in a future time. This time value indicates the number of minutes relative to the creation time of this message, as established by the MetaInformation message.

SpeedVector

SpeedVector provides a set of section speed information details at a point in a future time. This time value indicates the number of minutes, relative to the creation time of this message, as established by the MetaInformation message.

Default enabled information

Meta information & supplier and client information

The MetaInformation message type provides data shared by all traffic flow messages. It contains:

  • the creation time (TomTom uses the Epoch Linux Timestamp, which represents the number of seconds since January 1st, 1970 at UTC. For details, check https://www.unixtimestamp.com) and
  • the supplier and client information in the SupplierAndClientInfo message.
Example of MetaInformation with fields provided by default
1metaInformation {
2 createTimeUTCSeconds: 1696832700
3 supplierAndClientInfo {
4 clientID: "5b5977db-ab96-4599-b079-314a09cb9f204045d8f9"
5 supplierID: "TomTom Traffic Service"
6 }
7}

The SupplierAndClientInfo is crucial for accessing a flow feed using the recommended free-flow (ff) / non-free-flow (nff) update mechanism as explained in the section Request parameters under the optional URL parameter flowType.

Speed message default information

The Speed message subsumes all speed and travel time related information. It consists of the following default information:

  • averageSpeedKmph: The current average speed on the affected location in kilometers per hour.
  • travelTimeSeconds: The current average travel time to pass the affected location or free-flow travel time if average speed is 0 km/h (in seconds).
  • confidence: A measure of confidence values that rates the reliability of this speed estimate. The quality, amount, and age of live data for the affected location contribute to this score. It scales from 0 (no confidence) to 100 (fully confident about the estimate).
Example: default information in a flow message without prediction
1trafficFlow {
6 speed {
7 averageSpeedKmph: 11
8 travelTimeSeconds: 144
9 confidence: 81
10 }
11}

Note that the same default information is provided in Speed messages for the flow message type TrafficFlowWithPredictionPerSection.

Location referencing

Geographical representation of the road segments is an important part of the payload. There are two geographical representations that are supported: TMC and OpenLR. Since OpenLR prevents interpretation differences, licensing costs, map dependencies, or version dependencies, TomTom recommends using OpenLR instead of TMC. TMC based data is still offered for customers with existing platforms that need compatibility with their legacy systems.

OpenLR

OpenLR is a dynamic location referencing method that allows referencing of any road on the complete digital map. Because of its flexibility, it is possible to describe traffic events on high-level and lower-level road classes that are usually not covered by TMC. The method is available free of charge. The service uses binary format version 3, as described in the OpenLR whitepaper. The whitepaper, software developer kit, and open source reference implementations are available for download from the OpenLR website. TomTom offers support for third parties to implement and test their own implementations.

OpenLR example (here printed using C escape sequences)
1location {
2 openlr: "\v\254\320.!\367\n\033l\a\000Z\376\223\033\000"
3 lengthInMeters: 425
4}

Traffic Message Channel (TMC)

When using TMC as a geographical representation, travel times are measured by a TMC link. A TMC link is part of a TMC path. A TMC link is a sequence of road elements that starts at a TMC location, and ends at the next TMC location in the TMC table in the specified direction. You can recognize a TMC link by:

  • TMC table (country code, location table number, version).
  • Primary TMC location, defining the TMC point location at the end of the TMC link.
  • Direction, as defined by the TMC path.
  • An optional extent (the default value is 1).

The following examples shows a typical TMC link as used in our Service. The meaning of the information contained in the link is explained below in the section TMC link identifier.

TMC example
1location {
2 tmc: "D01p00015"
3}

Generally, the set of TMC link identifiers that can be used in a TrafficFlowGroup is static. That means that in subsequent snapshots, the same locations are used. However, this is not always the situation. Sometimes, the set of the TMC link identifiers that are used can be changed. These changes occur when a new TMC table is introduced.

TMC Chain Information is composed of the following parts CVVDLLLLL\[xE\[E\]\]:

PartDescription
C

Hexadecimal country code as described in IEC 62106.

VVThis is the TMC Location Table code.
D

TMC direction of the chain (defined by the TMC path). For possible values, see TMC direction.

LLLLL

TMC point location code. If the number is not five digits long, zeros are added at the beginning until there are five digits.

[xE[E]]

Either empty, when extent = 1, or fixed letter x followed by the extent (one or two digits).

Using the specified TMC table, the secondary location (start of the stretch) can be found from the primary location, the direction, and the extent. C, VV, and LLLLL correspond with the TMC Location Reference that is a unique identifier for a TMC location.

TMC direction

The possible values for D infer the direction of travel (secondary to primary location) along the TMC path.

ValueDirection
pPositive
nNegative

TMC examples

In this section, we demonstrate how to resolve TMC link identifiers on the receiver side. Here, we map the definition of each of the fields within the link identifier, and provide guidance on using the extent to find the secondary location.

Example 1: 817n39984x2

Given the TMC location data:

  • Country code: 8
  • Location table number: 17
  • Direction from secondary to primary location: negative
  • Primary location ID: 39984
  • Extent: 2

Interpret the TMC location data to resolve the secondary location:

  1. Invert direction: negative → positive.
  2. Since the resolved direction is positive, follow the positive offset path for 39984 in the TMC table for two extents.
  3. You will find the subsequent positive offsets are 39985 and 39986, therefore, the resolved secondary location is 39986.

Example 2: D01p27442

Given the TMC location data:

  • Country code: D
  • Location table number: 1
  • Direction from secondary to primary location: positive
  • Primary location ID: 27442
  • Extent: 1 (if the extent is not provided explicitly, then it is 1)

Interpret the TMC location data to resolve the secondary location:

  1. Invert direction: positive → negative.
  2. Since the resolved direction is negative, follow the negative offset path for 27442 in the TMC table for one extent.
  3. You will find the subsequent negative offset is 30080.

Example 3: TMC location reference with section offsets

1trafficFlowWithPredictionPerSection {
2 location {
3 tmc: "104p04168"
4 length: 3731
5 }
6 speedVector {
7 minutesInFuture: 0
8 sectionSpeed {
9 startOffsetInMeters: 0
10 [...]
11 }
12 sectionSpeed {
13 startOffsetInMeters: 1500
14 [...]
15 }
16 }
17}

Given the TMC location data:

104p04168 and section offsets: 0m, 1500m

  • Country code: 1
  • Location table number: 4
  • Direction from secondary to primary location: positive
  • Primary location ID: 4168
  • Extent: 1 (if extent not provided explicitly then it is 1)

Interpret the TMC location data to resolve the secondary location:

  1. Invert direction: positive -> negative.
  2. Since the resolved direction is negative, follow the negative offset path for 4168 in TMC table ( see the following TMC location table excerpt).
  3. The negative offset of 4168 is 4167, therefore, the resolved secondary location is 4167.

Apply section offset information on a resolved link:

  • Given the resolved secondary location, apply a section offset onto a location path measured from the secondary location.
  • In the following example, all section offsets are referring to 4167. That is, the first offset is 4167 itself and the second offset is 1500m away from 4167 along the location path to 4168.

Optionally activatable features

When the product is configured, there are some additional options that could be enabled or disabled depending on your specific preferences.

Dynamic sectioning

Dynamic sectioning describes the flow segments in smaller sections when conditions vary considerably within a longer road stretch. The Service uses the message type SectionSpeed to report sections. They are ordered by their offset relative to the start of the affected location. This offset is indicated by the startOffsetInMeters field of a SectionSpeed message. A section ends when the subsequent section starts. The last section ends at the end of the affected location indicated by the lengthInMeters field in the Location message.

Example
1trafficFlow {
2 location {
3 openlr: "\v\254\320.!\367\n\033l\a\000Z\376\223\033\000"
4 lengthInMeters: 425
5 }
6 speed {
7 averageSpeedKmph: 11
8 travelTimeSeconds: 144
9 confidence: 81
10 }
11 sectionSpeed {
12 startOffsetInMeters: 0
13 speed {
14 averageSpeedKmph: 2
15 travelTimeSeconds: 115
16 confidence: 81
17 }
18 }
19 sectionSpeed {
20 startOffsetInMeters: 48
21 speed {
22 averageSpeedKmph: 46
23 travelTimeSeconds: 29
24 confidence: 81
25 }
26 }
27}

Note that this feature is also available for the flow message type TrafficFlowWithPredictionPerSection.

Flow prediction

Flow prediction uses the message type TrafficFlowWithPredictionPerSection. The current speed and predictive speeds for 15, 30, 45 minutes in the future are reported with sectioning if applicable.

Example
1trafficFlowWithPredictionPerSection {
6 speedVector {
7 minutesInFuture: 0
8 sectionSpeed {
9 startOffsetInMeters: 0
10 speed {
11 averageSpeedKmph: 10
12 travelTimeSeconds: 238
13 }
14 }
15 sectionSpeed {
16 startOffsetInMeters: 673
17 speed {
18 averageSpeedKmph: 48
19 travelTimeSeconds: 63
20 }
21 }
22 }
23 speedVector {
24 minutesInFuture: 15
39 }
40 speedVector {
41 minutesInFuture: 30
56 }
57 speedVector {
58 minutesInFuture: 45
73 }
74}

[Deprecated] Flow prediction with message type TrafficFlowWithPrediction

The current speed and predictive speeds for 15, 30, 45 minutes in the future are reported for the entire road link. This configuration is deprecated as it misses the sectioning information for Dynamic Sectioning feeds and is only used with Traffic Flow Detailed Legacy.

An example of such a message is provided in trafficFlowWithPrediction.pb.txt.

Traffic condition

Provides a textual traffic condition indicator. When enabled, a categorization of current traffic condition is given. It can be any value out of seven values (see more details on FAQ about the definition of traffic conditions):

  • FREE_TRAFFIC

  • HEAVY_TRAFFIC

  • SLOW_TRAFFIC

  • QUEUING_TRAFFIC

  • STATIONARY_TRAFFIC

  • CLOSED

  • UNKNOWN

Example
1trafficFlow {
2 location {
3 openlr: "\013\265f\361\034J\374\001\0349\363A\006\013\001\014"
4 }
5 speed {
6 averageSpeedKmph: 23
7 travelTimeSeconds: 534
8 confidence: 99
9 trafficCondition: STATIONARY_TRAFFIC
10 }
11}

Note that this feature is also available for the flow message type TrafficFlowWithPredictionPerSection.

Relative speed

When enabled, the relative speed to the free-flowing speed is given as a ratio (e.g., 0.250 indicates a current real-time speed that is 25% of free flow speed) in field relativeSpeed in the Speed message.

Example
1trafficFlow {
2 location {
3 openlr: "\013\265f\361\034J\374\001\0349\363A\006\013\001\014"
4 }
5 speed {
6 averageSpeedKmph: 23
7 travelTimeSeconds: 534
8 confidence: 99
9 relativeSpeed: 0.229
10 }
11}

Note that this feature is also available for the flow message type TrafficFlowWithPredictionPerSection.

Time to usual

Provides the time duration (in minutes) for the average speed (of the entire location) of a flow message to return to the usual speed (speed profile). This feature is only available for flow message types TrafficFlowWithPredictionPerSection.

Example
1trafficFlowWithPredictionPerSection {
47 timeToUsualInMinutes: 26
48}

HOV Flow

Adds separate speed entries for lanes reserved for high-occupancy vehicles, for now only the current speed for the whole location is available.

The following example shows TrafficFlow message with two speed entries, one for the regular lanes and one for the HOV lane(s).

Example
1trafficFlow {
2 location {
3 openlr: "\v\251\003-!\331\326\001\f!\002K\371\264\001\037"
4 lengthInMeters: 1939
5 }
6 speed {
7 averageSpeedKmph: 76
8 travelTimeSeconds: 92
9 confidence: 100
10 }
11 speed {
12 averageSpeedKmph: 90
13 travelTimeSeconds: 78
14 confidence: 100
15 speedCondition {
16 laneType: HIGH_OCCUPANCY
17 }
18 }

Note that this feature is also available for the flow message type TrafficFlowWithPredictionPerSection.

Map version

Provides name and version of the map that was used to create the content. The map version is reported with the mapVersion field in the MetaInformation message.

Example, minimal snapshot with a single message and meta information
1metaInformation {
2 createTimeUTCSeconds: 1696833480
3 supplierAndClientInfo {
4 clientID: "5b5977db-ab96-4599-b079-314a09cb9f204045d8f9"
5 supplierID: "TomTom Traffic Service"
6 }
7 mapVersion: "nam2023.06.060"
8}
9trafficFlow {
20 }
21}

Note that this feature is also available in snapshots with the flow message type TrafficFlowWithPredictionPerSection.