Traffic Flow - Intermediate Service - Protobuf

Last edit: 2023.12.07

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

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

Standard configurations

TomTom offers traffic flow data to customers. The most basic data type is speed information and travel times by segment. TomTom configures a custom product based upon your specific needs. The product is static, so included regions and features are fixed (once the product is configured).

Optional configurations

The Service gives users traffic flow data with highly customizable configuration options, in addition to the standard configuration.

Option

Description

Dynamic sectioning

It describes the road links in smaller sections when conditions vary considerably within a longer road stretch.

Flow prediction

When enabled, the current and future speed information to a location at several points in time is provided. More information on the prediction horizon can be found in the flow feature matrix in the FAQ.

Relative speed

When enabled, the relative speed is provided. This is defined as the ratio of average speed to free-flowing speed (for example, 0.250 indicates a current real-time speed that is 25% of free-flow speed).

Traffic condition

When enabled, the current traffic condition is given. This is expressed with one out of seven available values.

Time to usual

When enabled, it gives the time in minutes for speed to return to usual speed (from the speed profile). This feature is an add-on to the Flow prediction feature and only works in combination with that option.

Miles per hour

The average speed is additionally provided in mph (all speeds are provided by default in km/h).

HOV Flow

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

Map version

Provides the name and version of the map that was used to create the content.

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 request format
https://{baseURL}/tsq/hdf/{productName}/{apiKey}/content.proto[?flowType={flowType}]

The following is an example URL:

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

TomTom Traffic Flow Detailed / TomTom Traffic Flow Detailed Legacy

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

The following is an example URL:

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

Request parameters

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

Required parameters

Description

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), type of feed (HDF is the flow feed) and the location referencing method (TMC or OpenLR).


Value: e.g., DEU-HDF-TMC, DEU-HDF_DETAILED-OPENLR

apiKey


string

Authorization key for access to the API.


Value: Your valid API key.

Optional parameters

Description

flowType

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.

Headers

Description

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

Accept-Encoding

The TomTom Traffic Incidents bulk feed supports gzip compression of all response types. However, responses are compressed only when the requester states gzip support. This should be specified through the standard HTTP header Accept-Encoding. TomTom recommends using this header type as it significantly reduces the payload size.


Value: gzip

Response data

Response example

If you make the following request:

get
URL request example
https://cert-traffic.tomtom.com/tsq/hdf/DEU-HDF-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).

Additionally, the only messages that are present are TrafficFlow, TrafficFlowWithPrediction, or TrafficFlowWithPredictionPerSection. The actual message type depends on the specific product definition (see the product configuration options):

  • TrafficFlow : This message type is used with products that are NOT configured for prediction. Optionally, TomTom supports breaking up locations into sections.
  • TrafficFlowWithPrediction : This message type is used with products configured for prediction and NOT for breaking up locations into sections.
  • TrafficFlowWithPredictionPerSection : This message type is used with products configured for prediction AND breaks up locations into sections.

In any other case, only TrafficFlow is included in the response.

The following table gives detailed information about the different messages used in the data structure.

Protocol buffers message type

Description

TrafficFlowGroup

The traffic flow group is the top-level message. It provides meta data and the flow entries themselves.

MetaInformation

The meta information message 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), the supplier and client information, and the format version.

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

The traffic flow message assigns current and future speed information to a location at several points in time. It may also identify road blockages.

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. This message consists of:

  • The current average speed on the affected location in kilometers per hour.

  • The current average travel time to pass the affected location or free-flow travel time if average speed is 0 km/h (in seconds).

  • (optional) 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).

  • (optional) The relative current speed as a percentage of the free-flow speed.

  • (optional) A classification of the current traffic condition, it can be one of seven values (see the product configuration options).

  • (optional) A generic condition as to when the speed information is valid. For instance, we support lane type information to indicate that the speed is only relevant for high occupancy vehicle (HOV) lanes.

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

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.

Geographical representation

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 example (here printed using C escape sequences):

1location {
2 openlr: "\013\004\334L$\335\270\013?\261\003\371!%\013\021"
3}

TMC example:

1location {
2 tmc: "D01p00015"
3}

OpenLR

OpenLR (see http://www.openlr.org) 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.

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 path 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.
  • The inclusion of internal / external road segments (see the following examples).
  • An optional extent (the default value is 1).

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\]\]:

Part

Description

C

Hexadecimal country code as described in IEC 62106.

VV

This 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 refer to the direction of travel (secondary to primary location) along the TMC path:

Value

Direction

Validity

p (lower case)

PositiveInternal + External

n (lower case)

NegativeInternal + External

+

PositiveExternal

-

NegativeExternal

P (upper case)

PositiveInternal

N (upper case)

NegativeInternal

If the extent > 1 then the value for <direction> must be 'p' or 'n', including all internal and external road segments. See the section Internal and external road segments for more details.

Internal and external road segments

To know exactly where a TMC link starts and ends, you should understand the concept of internal and external road segments. For each TMC point location and each direction, a composition is made of road segments that are part of the TMC location. An example of this is a highway junction or the roads between the exit and the entry. These are the internal road segments.

Furthermore, a path of road segments is constructed, connecting the TMC locations. The road segments between two TMC locations are the external road segments, which are assigned to the TMC location where the path is leading.

If two consecutive TMC locations have an overlap or a reverse order in the TomTom map, they can be combined into one TMC link with an extent > 1. Typically, a TMC link includes both the internal and external road segments of a TMC location, so a TMC link usually starts at the end of the secondary location and ends at the end of the primary location. Sometimes, the travel time is provided just for the internal road segments or the external road segments, though this is unusual. This is indicated in the TMC link identifier.

Examples

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: D01+27442

Given the TMC location data:

  • Country code: D
  • Location table number: 1
  • Direction from secondary to primary location: positive (external only)
  • Primary location ID: 27442
  • Extent: 1 (if 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 TMC table for one extent.
  3. You will find the subsequent negative offset is 30080.
  4. Now follow the path for 27442 in that direction and only select segments that are marked as the external part of 27442.

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

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.

Product configuration options

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

Option

Description

Example

Dynamic sectioning

Allows sectioning: describing the road links in smaller sections when conditions vary considerably within a longer road stretch.

Flow prediction

Flow prediction is supported in two flavors, each variant uses a specific flow message type:

  • TrafficFlowWithPrediction: The current speed and future speeds are reported for the entire road link.

  • TrafficFlowWithPredictionPerSection: The current speed and predictive speeds for 15, 30, 45 minutes in the future are reported with sectioning if applicable. Predictive speeds beyond 45 minutes are reported for the entire road link.

Examples for each possible flow message type when prediction is enabled:

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

A TrafficFlow message with stationary traffic: trafficFlow-trafficCondition.pb.txt

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

A TrafficFlow message with relativeSpeed: trafficFlow-relativeSpeed.pb.txt

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 TrafficFlowWithPrediction and TrafficFlowWithPredictionPerSection.

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.

A TrafficFlow message with two speed entries, one for the regular lanes and one for the HOV lane(s): trafficFlow-HOV.pb.txt

Map version

Provides name and version of the map that was used to create the content. The map version is reported as part of the meta information of a traffic flow snapshot.

A snaphot with a single TrafficFlow message and a MetaInformation message with field mapVersion: trafficFlow-mapVersion.pb.txt