Traffic Flow - Protobuf
Important notes:
- This TomTom Orbis API is in public preview.
- This API is powered by the TomTom Orbis Maps.
- See the TomTom Orbis Maps documentation for more information.
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.
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.
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/{Your_API_Key}/content.proto
The following is an example cURL request:
curl --compressed -XGET 'https://cert-traffic.tomtom.com/tsq/hdf-detailed/DEU/{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 |
---|---|
| Base URL for calling the API. |
| 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 other information
like the location referencing method. |
| Authorization key for access to the API. |
Optional parameters | Description |
---|---|
| When the feed is requested without the parameter
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). |
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 not necessary. For more information see our page about Gzip compression.
Headers | Description |
---|---|
If-Modified-Since | TomTom recommends using the standard HTTP header
|
Response data
Response codes
Response code | Description |
---|---|
200 OK | Indicates that the request has succeeded. The response body will contain the requested data. |
304 Not Modified | Only used if the |
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 |
Response example
If you make the following request:
https://cert-traffic.tomtom.com/tsq/hdf-detailed/DEU/{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: 14520929103 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: 515 travelTimeSeconds: 33416 confidence: 9717 relativeSpeed: 0.10618 trafficCondition: STATIONARY_TRAFFIC19 }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_v11.proto. TomTom supports schema version 11 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 type | Description |
---|---|
TrafficFlowGroup | The traffic flow group is the top-level message.
It provides meta data (see |
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. |
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 |
SpeedVector |
|
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.
1metaInformation {2 createTimeUTCSeconds: 16968327003 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 parameterflowType
. The same mechanism needs to be applied for requesting Identifier-based location referencing using OSM way IDs.
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).
1trafficFlow {6 speed {7 averageSpeedKmph: 118 travelTimeSeconds: 1449 confidence: 8110 }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:
- by default OpenLR location referencing is used,
- optionally Identifier-based location referencing based on OSM way IDs can be provided.
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. 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.
1location {2 openlr: "\v\254\320.!\367\n\033l\a\000Z\376\223\033\000"3 lengthInMeters: 4254}
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.
1trafficFlow {2 location {3 openlr: "\v\254\320.!\367\n\033l\a\000Z\376\223\033\000"4 lengthInMeters: 4255 }6 speed {7 averageSpeedKmph: 118 travelTimeSeconds: 1449 confidence: 8110 }11 sectionSpeed {12 startOffsetInMeters: 013 speed {14 averageSpeedKmph: 215 travelTimeSeconds: 11516 confidence: 8117 }18 }19 sectionSpeed {20 startOffsetInMeters: 4821 speed {22 averageSpeedKmph: 4623 travelTimeSeconds: 2924 confidence: 8125 }26 }27}
Note that this feature is also available for the flow message type TrafficFlowWithPredictionPerSection
.
Optionally activatable features
When the product is configured, there are some additional options that could be enabled or disabled depending on your specific preferences.
Identifier-based location referencing using OSM way IDs
Identifier-based location referencing OSM way IDs (hereafter called 'IDLR-OSM') is offered as an alternative method of location referencing besides OpenLR.
To get OSM way IDs from the feed, it must be requested with the URL parameter
flowType=ff
. How exactly this parameter is used is explained in the section Request parameters.
The following example shows a trafficFlow
message with an IDLR-OSM in the segmentIds
field indicated
by type: OSM_WAY_ID
that is composed of six OSM way IDs. All IDs use the forward direction, the first ID uses a start-offset,
the second through fifth IDs have no offsets, and the sixth ID uses an end-offset.
The affected location is the concatenation of all IDs minus the offset information.
1trafficFlow {2 location {3 openlr: "\v\211\302\310.P\211\033n\36418\324\253\033r\344\360I\324\036\033m\350>W\331\341\033l\3572Y\333t\033y\377\344"4 lengthInMeters: 285335 segmentIds {6 type: OSM_WAY_ID7 segmentId {8 id: 2309102499 backwards: false10 startOffsetInMeters: 303111 }12 segmentId {13 id: 63155031514 backwards: false15 }16 segmentId {17 id: 63155031318 backwards: false19 }20 segmentId {26 backwards: false27 }28 segmentId {29 id: 40670254730 backwards: false31 endOffsetInMeters: 1131732 }33 }34 }35 speed {36 averageSpeedKmph: 6537 travelTimeSeconds: 158038 confidence: 10039 }40}
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.
1trafficFlowWithPredictionPerSection {6 speedVector {7 minutesInFuture: 08 sectionSpeed {9 startOffsetInMeters: 010 speed {11 averageSpeedKmph: 1012 travelTimeSeconds: 23813 }14 }15 sectionSpeed {16 startOffsetInMeters: 67317 speed {18 averageSpeedKmph: 4819 travelTimeSeconds: 6320 }21 }22 }23 speedVector {24 minutesInFuture: 1539 }40 speedVector {41 minutesInFuture: 3056 }57 speedVector {58 minutesInFuture: 4573 }74}
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
1trafficFlow {2 location {3 openlr: "\013\265f\361\034J\374\001\0349\363A\006\013\001\014"4 }5 speed {6 averageSpeedKmph: 237 travelTimeSeconds: 5348 confidence: 999 trafficCondition: STATIONARY_TRAFFIC10 }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.
1trafficFlow {2 location {3 openlr: "\013\265f\361\034J\374\001\0349\363A\006\013\001\014"4 }5 speed {6 averageSpeedKmph: 237 travelTimeSeconds: 5348 confidence: 999 relativeSpeed: 0.22910 }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
.
1trafficFlowWithPredictionPerSection {47 timeToUsualInMinutes: 2648}
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).
1trafficFlow {2 location {3 openlr: "\v\251\003-!\331\326\001\f!\002K\371\264\001\037"4 lengthInMeters: 19395 }6 speed {7 averageSpeedKmph: 768 travelTimeSeconds: 929 confidence: 10010 }11 speed {12 averageSpeedKmph: 9013 travelTimeSeconds: 7814 confidence: 10015 speedCondition {16 laneType: HIGH_OCCUPANCY17 }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.
1metaInformation {2 createTimeUTCSeconds: 16968334803 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
.