TomTom Traffic Incidents - Intermediate Service - Protobuf
Introduction to TomTom Traffic Incidents - Intermediate Service – Protobuf
Executive summary
The TomTom Traffic Incidents - Intermediate Service – Protobuf (hereafter called ‘Service’) is designed for server to server integration with traffic control center, routing, navigation, and mapping applications.
The Service provides the latest real-time information about traffic incidents, their causes and impacts on travelers. Typical traffic incidents include accidents, road construction projects, traffic jams, travel weather warnings, road closures, and any other road-related situation that could potentially cause a delay. This service uses protocol buffers (protobuf), a third-party language and platform neutral mechanism for serializing structured data.
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 information is intended to be used by TomTom partners and customers (decision makers and developers).
What is the TomTom Traffic Incidents – Intermediate Service – Protobuf?
Standard configurations
TomTom offers traffic incident data to customers. In the basic configuration, TomTom provides customers information on traffic congestion and other roadwork related traffic events.
Each traffic incident is represented in a separate message in our proprietary protocol buffers format. This information is organized by country-based datasets. The product is static. This means that the included regions and features are fixed, once the product is configured. Products are customer-specific.
Detailed information about the physical representation in protocol buffers is found in the section, Standard information.
Optional configurations
The Service provides users traffic incident data with highly customizable optional configuration, in addition to the standard configuration.
Detailed information about the physical representation in protocol buffers can be found below in Optional information.
Option | Description |
---|---|
Traffic event end time |
This option predicts the expected ending time for the traffic event. |
Jam tendency |
This feature indicates whether a jam is improving, remaining stable, or becoming worse. |
Weather-related messages |
This feature reports messages for road segments that could be impacted by severe weather. |
Jam ahead warnings |
Selecting this option generates special warning messages when a location registers high-speed differences. Specifically, when the tail end of the jam is projected to intercept oncoming traffic, creating a potentially dangerous situation. The user can enable messages for only jam ahead warnings or have them delivered next to all regular messages. This option is not available with TMC location referencing. |
Average speed for journalistic events |
Selecting this option adds the average speed values for journalistic messages (for example, road works or lane restrictions). This is the average speed as measured by TomTom. |
Turn-dependent jams |
Selecting this option provides the user with turn-dependent jams information. The user receives messages when a portion of the jam is projected to affect travel only if following in the direction of the jam. Common use cases include: congestion on exit ramps, entry ramps, turn-lanes, and so on. This feature is only available in combination with location referencing method OpenLR. |
Incident node name |
Selecting this option provides node names for cross-streets at the beginning and end of the road segment. |
Road number |
Selecting this option provides the road identifier or road number of the affected location (for example, VA-606). |
Future incidents |
Selecting this option includes incidents whose start time is in the future (for example, planned roadworks or road closures). |
Map version |
This option provides the names and versions of the maps that were used to create the content. |
Jam evolution |
Selecting this option predicts how congestion incidents evolve over time. |
RESTful API
The Service uses RESTful API (Representation State Transfer) technology. Since you only need to use one URL, the service is relatively uncomplicated to use.
How do you make a request?
Format
To make a request, the URL should be constructed as shown in the following sections.
Important
|
To use this service, insure that all prerequisites are met as described in the section, “A secure connection” at https://developer.tomtom.com/intermediate-traffic-service. |
The sample URL is formatted as follows:
https://<baseURL>/tsq/hdt/<productName>/<key>/content.proto
The following is an example URL:
https://traffic.tomtom.com/tsq/hdt/DEU-HDT-OPENLR/<APIKEY>/content.proto
Parameters
The following table provides a detailed explanation of the available fields that were previously shown in the Format section.
Parameter | Description | Req’d? | Type / Values |
---|---|---|---|
baseURL |
Base URL for calling the API. |
Yes |
traffic.tomtom.com |
productName |
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 (HDT is the incident feed), and the location referencing method (TMC or OpenLR). |
Yes |
e.g. |
key |
Authorization key for access to the API. |
Yes |
String |
Recommended HTTP headers
Since incident feeds can be very large, TomTom recommends optimizing the information transmission as much as possible. By doing this, the client receives more up-to-date information.
-
If-Modified-Since
TomTom recommends using the standard HTTP headerIf-Modified-Since
with the last value ofLast-Modified
received. When this header is used properly, you avoid unnecessarily downloading identical content. For details, see HTTP/1.1 standard (RFC2616 section 14.25). -
Accept-Encoding: Gzip
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 headerAccept-Encoding: gzip
. TomTom recommends using this header type as it significantly reduces the payload size.
Response you receive after a request is made.
Response example
If you make the following request:
https://traffic.tomtom.com/tsq/hdt/DEU-HDT-OPENLR/<APIKEY>/content.proto
You can expect the following response:
metaInformation { creationTimeUTCSeconds: 1575913230 formatVersion: 1 mapVersion: "nam2019.09.011" } trafficIncidents { trafficIncidentManagement { id: "TTI-3942e76f-5ce4-36e6-8f84-692d87ac7fa1-TTL47457543462496" version: 1 reportingTimeUTCSeconds: 1575913200 } location { type: LINEAR openlr: "\v\251M\314\032\22276\323\001\377\301\377\3336\005" fromNodeName: "San Jose" toNodeName: "Technology Dr" lengthAffectedMeters { value: 71 } } event { trafficCondition: QUEUING_TRAFFIC endTimeUTCSeconds: 1575914430 tendency: TRAFFIC_BUILDING_UP averageSpeedHmph { value: 33 } delaySeconds { value: 51 } alertCEventCode { mainEvent: 108 } } } [...]
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 3 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. See also: http://code.google.com/p/protobuf or https://developers.google.com/protocol-buffers for more information.
Our output type uses the proprietary TomTom protocol buffers message types. The data structure of the protocol buffer output is defined by a .proto definition file. TomTom supports schema version 1 and above.
How the data is organized
Overall feed information: MetaInformation
The message type MetaInformation provides information relevant for the whole feed, such as map version, creation time of the content and so on.
Traffic information: TrafficIncident list
The traffic information is provided as list of TrafficIncident messages. This list is the snapshot of the latest traffic data. The service does not support a delta mechanism. Therefore, incremental updates are not possible.
TrafficIncident message
A TrafficIncident is a traffic or travel incident comprised of one or more traffic or travel situations. These situations are linked by one or more causal relationships and apply to related locations. Each traffic or travel situation is represented by one or more Alert-C event codes.
Validity period
A traffic incident has a validity period that is comprised of two fields defined in message type Event:
-
an optional startOverallStartTime, if incident is in the future,
-
an optional overallEndTime, if there is an expected end date.
Impact
If the current delay is available for a traffic incident, the delaySeconds is provided in message type Event.
Related traffic events
In some cases, there are multiple events that are related to each other. For instance, there can be a traffic jam that is caused by an accident. If the locations of these events overlap or are connected AND they occur in the same direction, then the events are contained in the same TrafficIncident. In that case, a single TrafficIncident contains more than one event code. The main event of such a combined TrafficIncident is reflected by the mainEvent field within the message type AlertCEventCode and the trafficCondition field within the message type Event. The related events are listed in the field additionalEvents within the message type AlertCEventCodes.
Sometimes, it is possible that two events are related to each other, but do not overlap. For instance, one event contains a diversion advice, located at a highway intersection. Since the road is blocked farther along the segment, that is described in a different TrafficIncident. In that case, the traffic information snapshot does not contain a reference from one event to the other.
Speed information
All speeds are provided as hectometers per hour and are encoded as integer types. This speed unit enabled greater precision than integer speeds in kilometers per hour. It also supports compact variable length compression as compared to floats.
Usage of protocol buffers wrapper types and default values
Protocol buffers version 3 introduced default values for integer types. These values are not contained in serialized binary data. On the decoder side, it is not obvious if the default represents a valid value or a value that must be ignored. To avoid this ambiguity, wrappers are used in the schema whenever different interpretations are possible. A wrapper is a message that contains a primitive type (for example, uint32). Examples include:
- speed values that use wrappers to distinguish speed "0" from speed "not set,"
- delay values that use wrappers to distinguish delay "0" (this indicates free-flow condition) from delay "not set,"
- length values that use wrappers to distinguish length "0" from length "not set."
When a wrapper type contains the default value then it must be evaluated as set. For example, a message type with one field modelled as wrapped unsigned integer such as:
import "google/protobuf/wrappers.proto"; message MyMessage { google.protobuf.Uint32 myValue = 1; }
When on the decoder side a message of that type with the following content has been received:
myValue { }
then the value field of wrapper myValue must be interpreted as "0."
When wrapper types are not used, then the defaults either have a meaning or they are not expected. Examples include:
- strings: the empty string indicates that the value is "not set."
- UTC seconds: "0" can be assumed as "not set." The reason for this is that the service does not provide historic data.
Location
Every TrafficIncident contains a Location message that describes the affected location of the incident.
OpenLR location referencing
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 both high level and lower level road classes that are not usually covered by Traffic Message Channel (TMC). TomTom uses the terms TMC and Alert-C interchangeably throughout this documentation; they have the same meaning. OpenLR is available free of charge. The Service uses binary format version 3, as described in the OpenLR whitepaper. The whitepaper, software development kit, and open source reference implementation can be downloaded from the OpenLR website mentioned previously. TomTom offers support for third parties who want to test their own implementations.
TMC (Alert-C) location referencing
The TMC feed uses Alert-C as the location referencing method. An Alert-C location reference contains a reference to a specific version of a TMC Location Table. TMC allows referrals to area, point, or linear locations. Offset information is used to identify an exact location.
Standard information
The following table details the standard information provided by the Service.
Field Name (part of) | Description | Example |
---|---|---|
id (TrafficIncidentManagement) |
Each traffic incident has a unique identifier. This identifier is established when the traffic incident is first created. As long as the traffic incident exists, this identifier will always be present within the system. The unique identifier has a fixed prefix "TT", followed by a string. No further assumptions should be made about the identifier. The identifier is unique across all supported countries. |
trafficIncidents { trafficIncidentManagement { id: "TTI-3942e76f-5ce4-36e6-8f84-692d87ac7fa1-TTR47235942297649" [...] } } |
reportingTimeUTCSeconds (TrafficIncidentManagement) | Time when the incident was reported. |
trafficIncidents { trafficIncidentManagement { [...] reportingTimeUTCSeconds: 1575982800 } [...] } |
location (TrafficIncident) | The location indicates where an incident occurs. TMC and OpenLR (binary version 3) are the supported location referencing methods. Each Location message contains a location type indicator that can be used to filter messages (e.g. Jam Ahead Warnings are reported as point locations). |
TMC: trafficIncidents { [...] location { type: LINEAR tmc { countryCode: 1 tableNumber: 5 tableVersion: "7.1" primaryLocation: 9277 primaryLocationOffsetMeters { value: 14730 } secondaryLocation: 9136 secondaryLocationOffsetMeters { } direction: POSITIVE } [...] } [...] } OpenLR: trafficIncidents { [...] location { type: LINEAR openlr: "\v\251M\314\032\22276\323\001\377\301\377\3336\005" [...] } [...] } |
alertCEventCode (Event) | The Alert-C event code describing the traffic incident. There can be one or more codes. For more information see the section, Related traffic events. |
trafficIncidents { [...] event { alertCEventCode { mainEvent: 500 additionalEvents: 701 additionalEvents: 638 } } } |
trafficCondition (Event) |
The traffic condition describes the effect on the traffic flow along the affected location. It allows a simple filtering of traffic incidents according to basic types:
The traffic condition represents the nature of the main event! |
A stationary traffic (101) congestion event: trafficIncidents { [...] event { trafficCondition: STATIONARY_TRAFFIC [...] alertCEventCode { mainEvent: 101 } } [...] } Roadworks event (710) with additional information of changed roadworks layout (810). Note: TRAFFIC_FLOW_UNKNOWN is using enum value 0. For that reason, it is not explicitly contained in the feed but assumed by the decoder side (as 0 is the default value for enums). See the official documentation on protocol buffers. trafficIncidents { [...] event { [...] alertCEventCode { mainEvent: 710 additionalEvents: 810 } } [...] } Closure event with additional roadworks event: trafficIncidents { [...] event { trafficCondition: CLOSED [...] alertCEventCode { mainEvent: 401 additionalEvents: 701 } } [...] } |
averageSpeedHmph (Event) |
The average speed in hectometers per hour. Speed is always available for all congestion events. Speed for journalistic events can be optionally configured (see Optional configurations). |
trafficIncidents { [...] event { [...] averageSpeedHmph { value: 33 } } } |
delaySeconds (Event) |
Additional travel time due to the event when compared to normal speed. |
trafficIncidents { [...] event { [...] delaySeconds { value: 51 } } } |
comments (Event) | A TrafficIncident may contain language-specific text. For example, this can be a diversion advice, provided by the network manager, or some other free text. |
trafficIncidents { [...] event { comments { lang: "DE" value: "Wegen Reparaturarbeiten sind auf der Münchener Straße in Fahrtrichtung Benrath wechselseitig jeweils ein Fahrstreifen und der Standstreifen gesperrt." } } } |
Optional information
The Service has the following possible optional extensions. Additional details are shown in Optional configurations.
Option | Implementation | Example |
---|---|---|
Traffic event end time |
The feature is represented by the field endTimeUTCSeconds within the message type Event. This field is expressed as a UTC time (e.g. 14:22 UTC). These end times may be created by TomTom or originate from local road authorities (for journalistic events). |
trafficIncidents { [...] event { [...] endTimeUTCSeconds: 1576339200 } } |
Jam tendency |
The feature is supported for congestion events and is represented under tendency within the message type Event. The following values may be present:
|
trafficIncidents { [...] event { trafficCondition: SLOW_TRAFFIC [...] tendency: TRAFFIC_BUILDING_UP [...] } } |
Weather-related messages |
Snow or heavy rain conditions use suitable Alert-C event codes. The following Alert-C event codes and weather conditions are used for the field mainEvent within the message type AlertCEventCode:
|
|
Jam ahead warnings |
An OpenLR point along line reference is used for this traffic incident type. The jam ahead warning is recognized by a location with type POINT in combination with a traffic condition that indicates a congestion event. |
trafficIncidents { [...] location { type: POINT openlr: "+\251I.\032\250^\001\v\017\002\231\375\203\001]W" [...] } event { trafficCondition: STATIONARY_TRAFFIC averageSpeedHmph { value: 190 } alertCEventCode { mainEvent: 101 } } } |
Average speed for journalistic events |
We provide measured average speeds for different journalistic event types. The speed and delay information are reported with the fields averageSpeedHmph and delaySeconds within the message type Event. |
Example of a roadworks element with speed and delay information: trafficIncidents { [...] event { averageSpeedHmph { value: 191 } delaySeconds { value: 11 } alertCEventCode { mainEvent: 701 additionalEvents: 810 } } } |
Turn-dependent jams |
We provide a field called conditionalOffsetMeters within the message type Location. To find the actual affected location, the offset must be applied from the end of the location. For more information, see Figure 1. |
trafficIncidents { [...] location { type: LINEAR openlr: "\v\271\365\312\025\016\374\"\217\b\377\366\376N&E+" [...] conditionalOffsetMeters { value: 131 } } event { trafficCondition: QUEUING_TRAFFIC averageSpeedHmph { value: 125 } delaySeconds { value: 96 } alertCEventCode { mainEvent: 108 } } } |
Incident node name |
We provide two fields called fromNodeName and toNodeName within the message type Location. |
trafficIncidents { [...] location { [...] fromNodeName: "Nord-West-Umfahrung / Gottlieb-Daimler-Straße" toNodeName: "Nürtinger Straße (L1205)" [...] } [...] } |
Road number |
We provide a field called roadNumber within the message type Location. |
Example for the German freeway (Autobahn) A3: trafficIncidents { [...] location { [...] roadNumber: "A3" [...] } [...] } |
Future incidents |
We provide the field startTimeUTCSeconds within the message type Event. The start time of future incidents is after the snapshot creation time (see creationTimeUTCSeconds in Standard information). |
metaInformation { creationTimeUTCSeconds: 1570000000 [...] } trafficIncidents { [...] event { [...] startTimeUTCSeconds: 1575000000 [...] } } |
Map version |
We provide mapVersion within the message type MetaInformation. |
metaInformation { [...] mapVersion: "nam2019.09.011" } |
Jam evolution |
We provide prediction within the message type TrafficIncident. The prediction is a location element and multiple prediction states. The location covers the complete extension of the predicted congestion over time. It is represented by the message type Location and the same features are supported as with the regular location field inside TrafficIncident. The location element within TrafficIncident is also set for congestion events that contain prediction. However, this location is only valid for the speed information provided in the Event message. PredictionState is the message type that represents a prediction state. Each state is identified by a time (the field timeUTCSeconds) that indicates when the state is valid. The list of states is ordered by that prediction time. A prediction state provides:
|
trafficIncident { trafficIncidentManagement { [...] } event { [...] } location { [...] } prediction { location { type: LINEAR openlr: "\v\254\r]\030H\242\001\026E\357|\001l\001\t" } predictionStates { timeUTCSeconds: 1575913230 speedHmph { value: 324 } freeFlowSpeedHmph { value: 1121 } lengthOffsetMeters { } lengthAffectedMeters { value: 436 } } predictionStates { timeUTCSeconds: 1575913499 speedHmph { value: 324 } freeFlowSpeedHmph { value: 1121 } lengthOffsetMeters { } lengthAffectedMeters { value: 436 } } [...] } } |
Figure 1 Turn dependent jams definitions