Traffic Flow - Protobuf

Purpose

The TomTom Traffic Flow – Intermediate Service – Protobuf endpoint (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).

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.

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

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

The following is an example URL request:

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

The following is an example cURL request:

curl -XGET 'https://cert-traffic.tomtom.com/tsq/hdf/DEU-HDF-OPENLR/{Your_API_Key}/content.proto'

TomTom Traffic Flow Detailed / TomTom Traffic Flow Detailed Legacy

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

The following is an example URL request:

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

The following is an example cURL request:

curl -XGET '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.

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.

Response data

Response example

If you make the following request:

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.

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

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

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.

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

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.

Product configuration options

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