Sorry, you need to enable JavaScript to visit this website.
Intermediate Traffic Service
Request access

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.
DE-HDT-OPENLR
DE-HDT-TMC

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 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 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 header Accept-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:

  • congestions: HEAVY_TRAFFIC, SLOW_TRAFFIC, QUEUING_TRAFFIC, STATIONARY_TRAFFIC
  • closures: CLOSED
  • other journalistic events: TRAFFIC_FLOW_UNKNOWN

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:

  • TRAFFIC_BUILDING_UP

  • TRAFFIC_EASING

  • TRAFFIC_STABLE

  • TENDENCY_UNKNOWN

 
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:

  • Alert-C event code 1101 (snow)

  • Alert-C event code 1106 (hail)

  • Alert-C event code 1107 (sleet)

  • Alert-C event code 1109 (heavy rain)

 

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:

  • the predicted speed (in the field speedHmph),
  • an offset value (in the field lengthOffsetMeters) and affected length (in the field lengthAffectedMeters) to localize the affected location along the overall predicted location, and
  • the free-flow speed (in the field freeFlowSpeedHmph) along the affected location.
 
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