Sorry, you need to enable JavaScript to visit this website.

TomTom Traffic Incidents – Intermediate Service – DATEX II

Introduction to TomTom Traffic Incidents - Intermediate Service – DATEX II

Executive summary

The TomTom Traffic Incidents - Intermediate Service – DATEX II (hereafter called ‘Service’) is based on DATEX II v1.0. DATEX II is a standard for information exchange between traffic control centers, service providers, and application developers.

The Service responds with the latest real-time information about traffic incidents, including their causes and impacts. Typical traffic incidents include accidents, road construction projects, traffic jams, travel weather warnings, road closures, or any road-related situation that could potentially cause a delay.

In this document, we discuss how to access the service and the features that are included.

Important
TomTom only supports the Intermediate Service with the use of the TomTom customized DATEX II schema, available for download from our website (linked previously and later in this document). Using the Service with the standard DATEX II schema will disable the functionality that is included with the Service. Therefore, the standard DATEX II schema is not supported.

Scope

This page gives basic information on the Service and shows how to configure this to work with your environment. The fields are described in two sets of tables. One that defines them in a logical way, and the other describes in detail how they are represented in DATEX II format. Basic knowledge of installing and using XML-based schemas is necessary.

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 – DATEX II?

Standard configurations

TomTom offers traffic incident data to customers. The basic configuration offers customers information on traffic congestion and other roadwork related traffic events.

Each traffic incident is represented in a DATEX II event, and we add an AlertC code with the same meaning. This AlertC code allows the user to customize the content, as they see fit. This information is configured in country-based datasets. Since the product is static, included regions and features are fixed once the product is configured.

Detailed information about the physical representation in DATEX II can be found below in Standard information.

Optional configurations

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

Detailed information about the physical representation in DATEX II can be found below in Optional information.



Option Description

Traffic event end time

Selecting this option predicts the time at which TomTom expects the event to have ended.

Jam tendency

This feature provides an indication of 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).

Dynamic speed limit messages

Selecting this option provides the variable speed limit information from the relevant traffic authority.

Future incidents

Selecting this option includes incidents whose start time is in the future (for example, planned roadworks or road closures).

Map version

Provides names and versions of the maps that were used to create the content.

RESTful API

The Service uses RESTful API (Representation State Transfer) technology. Because you only need to use one URL, the service is simple to use.

‘Simple HTTP server’ profile

The interface supports the client pull method, also known as the simple HTTP server profile. The profile is described in the Software Developers Guide and Exchange Platform Specific Model (see http://www.datex2.eu for details). TomTom does not support the SOAP envelope, described in the Software Developers Guide.

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

The following is an example URL:

https://traffic.tomtom.com/tsq/hdt/DEU-HDT-OPENLR/<APIKEY>/content.xml

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

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

You can expect the following response:

<d2LogicalModel modelBaseVersion="1.0">
    <exchange>
        <supplierIdentification>
            <country>nl</country>
            <nationalIdentifier>TomTom Traffic Service</nationalIdentifier>
        </supplierIdentification>
    </exchange>
    <payloadPublication xsi:type="SituationPublication" lang="en">
        <publicationTime>2015-12-14T12:09:03Z</publicationTime>
        <publicationCreator>
            <country>other</country>
            <nationalIdentifier>a557f357-4196-4f7f-8002-8c8aa0e18193</nationalIdentifier>
        </publicationCreator>
        <situation id="TTI-a557f357-4196-4f7f-8002-8c8aa0e18193-TTL119738232499376">
            <headerInformation>
                <confidentiality>internalUse</confidentiality>
                <informationStatus>real</informationStatus>
                <urgency>urgent</urgency>
            </headerInformation>
            <situationRecord xsi:type="AbnormalTraffic" id="TTI-a557f357-4196-4f7f-8002-8c8aa0e18193-TTL119738232499376-1">
                <situationRecordCreationTime>2015-12-14T12:09:03Z</situationRecordCreationTime>
                <situationRecordVersion>1</situationRecordVersion>
                <situationRecordVersionTime>2015-12-14T12:09:03Z</situationRecordVersionTime>
                <situationRecordFirstSupplierVersionTime>2015-12-14T12:09:03Z</situationRecordFirstSupplierVersionTime>
                <probabilityOfOccurrence>probable</probabilityOfOccurrence>
                <validity>
                    <validityStatus>definedByValidityTimeSpec</validityStatus>
                    <validityTimeSpecification>
                        <overallStartTime>2015-12-14T12:09:03Z</overallStartTime>
                        <overallEndTime>2015-12-14T12:29:03Z</overallEndTime>
                    </validityTimeSpecification>
                </validity>
                <impact>
                    <delays>
                        <delayTimeValue>94.0</delayTimeValue>
                    </delays>
                </impact>
                <groupOfLocations>
                    <locationContainedInGroup xsi:type="Linear">
                        <locationExtension>
                            <openlr>
                                <binary version="3">CweksCU8dxt9DP8AAmQcSRE=</binary>
                            </openlr>
                        </locationExtension>
                    </locationContainedInGroup>
                </groupOfLocations>
                <situationRecordExtension>
                    <alertCEventCode>115</alertCEventCode>
                </situationRecordExtension>
                <abnormalTrafficType>slowTraffic</abnormalTrafficType>
                <trafficTrendType>trafficBuildingUp</trafficTrendType>
                <abnormalTrafficExtension>
                    <averageSpeed>18.0</averageSpeed>
                </abnormalTrafficExtension>
            </situationRecord>
        </situation>

[...]

    </payloadPublication>
</d2LogicalModel>

Response – DATEX II payload specification (analysis of the output received)

The payload in the output is formatted as DATEX II, which is a European standard for the exchange of Traffic and Travel Information. TomTom supports version 1. The DATEX II User Guide version 1.0 and the standard DATEX II XML schema version 1.0 are available from the DATEX II website (www.datex2.eu). Recommended documents are:

  • DATEX II User Guide version 1.0 (DATEXIIv1.0-UserGuide_v1.0.pdf)

  • A browsable DATEX II version 1.0 data dictionary (DATEXIIv1.0-DataDictionnary_v1.0.zip)

The Elaborated Data Publication, used by TomTom, is described in more detail in section 4.11 of the DATEX II User Guide version 1.0.

TomTom extended the data model with additional fields; the full XSD schema including extensions can be downloaded by clicking this link. It is a "Level B" extension of the standard XML schema: DATEXIISchema_1_0_1_0.xsd. Such an extension is interoperable with the "Level A" data model (see section 2.2.3 in the DATEX II User Guide version 1.0 for more information).

Standard information

The DATEX II data model has been extended to allow additional parameters. Some of these extensions are needed for the standard feed information (see also Standard configurations).




Field Name (part of) Description Example

averageSpeed (AbnormalTrafficExtensionType)

The average speed for congestion events, in km/h.

<situationRecord xsi:type="AbnormalTraffic" [...]>
    [...]
    <abnormalTrafficExtension>
        <averageSpeed>18.0</averageSpeed>
    </abnormalTrafficExtension>
</situationRecord>

alertCEventCode (SituationRecordExtensionType)

The Alert-C event code describing the SituationRecord. There can be zero or more codes. It is highly recommended to use the alertCEvent code to classify the incident and map to a list of categories that are to be supported (e.g. traffic jams, road closures, road works, lane closures, accidents, …)

Refer to ISO TS 14819-2 at http://www.iso.org for Alert-C codes and conventions.

<situationRecord [...]>
    [...]
    <situationRecordExtension>
        <alertCEventCode>115</alertCEventCode>
    </situationRecordExtension>
</situationRecord>

Optional information

The DATEX II data model has been extended to allow additional parameters. The Service has the following possible extensions. Additional details are shown in Optional configurations.




Option Implementation Example

Traffic event end time

The feature is represented by the overallEndTime under validity. This field is expressed as a UTC time (e.g. 14:22 UTC) These end times may be created by TomTom or originate from, for example, local road authorities (for journalistic events).

<situationRecord [...]>
    [...]
    <validity>
        <validityStatus>definedByValidityTimeSpec</validityStatus>
        <validityTimeSpecification>
            <overallStartTime>2018-08-14T08:00:00Z</overallStartTime>
            <overallEndTime>2018-12-24T00:00:00Z</overallEndTime>
        </validityTimeSpecification>
    </validity>
    [...]
</situationRecord>

Jam tendency

The feature is supported for situation record type AbnormalTraffic and is represented under trafficTrendType. The following values may be present:

  • trafficBuildingUp

  • trafficEasing

  • trafficStable

  • unknown

<situationRecord [...] xsi:type="AbnormalTraffic" [...]>
    [...]
    <trafficTrendType>trafficBuildingUp</trafficTrendType>
    [...]
</situationRecord>

Weather-related messages

Snow or heavy rain conditions use suitable Alert-C event codes and DATEX II classifications. These events are classified under poorEnvironmentConditions. The following Alert-C event codes and weather conditions are used:

  • Alert-C event code 1101 (snow), poor environment condition heavySnowfall

  • Alert-C event code 1106 (hail), poor environment condition hail

  • Alert-C event code 1107 (sleet), poor environment condition sleet

  • Alert-C event code 1109 (heavy rain), poor environment condition heavyRain

 

Jam ahead warnings

An OpenLR point along line reference is used for this message. The jam ahead warning is recognized by a locationContainedInGroup with type Point in combination with the presence of an averageSpeed.

<situationRecord [...] xsi:type="AbnormalTraffic" [...]>
    [...]
    <groupOfLocations>
        <locationContainedInGroup xsi:type="Point">
            <locationExtension>
                <openlr>
                    <binary version="3">KwchAiYFHQEfGf8LBSABUEc=</binary>
                </openlr>
            </locationExtension>
        </locationContainedInGroup>
    </groupOfLocations>
    [...]
    <abnormalTrafficExtension>
        <averageSpeed>29.0</averageSpeed>
    </abnormalTrafficExtension>
</situationRecord>

Average speed for journalistic events

We provide measured average speeds for different journalistic event types. We created DATEX II extensions with the field averageSpeed:

  • AccidentExtensionType

  • ConditionsExtensionType

  • EnvironmentalObstructionExtensionType

  • EquipmentDamageObstructionExtensionType

  • GeneralObstructionExtensionType

  • OperatorActionExtensionType

  • PoorRoadInfraStructureExtensionType

Example of a GeneralObstruction element:

<situationRecord [...] xsi:type="GeneralObstruction" [...]>
    [...]
    <generalObstructionExtension>
        <averageSpeed>59.6</averageSpeed>
    </generalObstructionExtension>
</situationRecord>

All other extension types listed on the left work the same way as GeneralObstruction.

Turn-dependent jams

We provide a field called conditionalOffset in the DATEX II extension SituationRecordExtensionType. To find the actual affected location, the offset needs to be applied from the end of the location. For more information, see Figure 1

<situationRecord [...]>
    [...]
    <situationRecordExtension>
        <alertCEventCode>115</alertCEventCode>
        <conditionalOffset>151</conditionalOffset>
    </situationRecordExtension>
    [...]
</situationRecord>

Incident node name

We provide two fields called fromNodeName and toNodeName in the DATEX II extension LocationExtensionType.

<situationRecord [...]>
    [...]
    <groupOfLocations>
        <locationContainedInGroup xsi:type="Linear">
            <locationExtension>
                [...]
                <fromNodeName>
                    <name>Nord-West-Umfahrung / Gottlieb-Daimler-Straße</name>
                </fromNodeName>
                <toNodeName>
                    <name>Nürtinger Straße (L1205)</name>
                </toNodeName>
                [...]
            </locationExtension>
        </locationContainedInGroup>
    </groupOfLocations>
    [...]
</situationRecord>

Road number

We provide a field called roadNumber in the DATEX II extension LocationExtensionType.

Example for the German freeway (Autobahn) A3:

<situationRecord [...]>
    [...]
    <groupOfLocations>
          <locationContainedInGroup xsi:type="Linear">
            <locationExtension>
                [...]
                <roadNumber>A3</roadNumber>
            </locationExtension>
        </locationContainedInGroup>
    </groupOfLocations>
    [...]
</situationRecord>

Dynamic speed limit messages

We provide a field called speedLimitKmH in the DATEX II extension SpeedsExtensionType. This extension is part of an advice of type Speeds of a SituationRecord element.

<situationRecord [...] xsi:type="VariableMessageSignSetting" [...]>
    [...]
    <advice xsi:type="Speeds">
        <speedAdvice>mandatorySpeedLimitInForce</speedAdvice>
        <speedsExtensionType>
            <speedLimitKmH>80.0</speedLimitKmH>
        </speedsExtensionType>
    </advice>
    [...]
</situationRecord>

Future incidents

We provide overallStartTime under the field validity of a SituationRecord element. This field is expressed as a UTC time (e.g. 14:22 UTC). The start time of future incidents is after the publication time.

<?xml version="1.0" ?>
<d2LogicalModel
    xmlns="http://datex2.eu/schema/1_0/1_0"
    modelBaseVersion="1.0">
    [...]
    <payloadPublication
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="SituationPublication" lang="en">
        <!-- time when snapshot was created -->
        <publicationTime>2018-09-01T00:00:00Z</publicationTime>
    <situation [...]>
        <situationRecord [...]>
           [...]
           <validity>
               <validityStatus>suspended</validityStatus>
               <validityTimeSpecification>
                  <!-- start time of the incident -->
                  <overallStartTime>2018-10-01T00:00:00Z</overallStartTime>
               </validityTimeSpecification>
           </validity>
           [...]
        </situationRecord>
    </situation>
<d2LogicalModel/>

Map version

This feature is supported by element mapVersion in complex type PayloadPublicationExtensionType.
<?xml version="1.0" ?>
<d2LogicalModel
    xmlns="http://datex2.eu/schema/1_0/1_0"
    modelBaseVersion="1.0">
    [...]
    <payloadPublication
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:type="SituationPublication" lang="en">
        [...]
        <payloadPublicationExtension>
            <mapVersion>eur2018.06</mapVersion>
        </payloadPublicationExtension>
        <!-- list of situation elements follows -->
        [...]
    </payloadPublication>
</d2LogicalModel>

Figure 1 Turn dependent jams definitions

How the data is organized

SituationPublication

The traffic information is provided as a SituationPublication. A SituationPublication contains a snapshot of the latest traffic data. No delta mechanism is supported, so incremental updates are not included. A SituationPublication can contain several different situations.

Situation

A situation represents a traffic or travel incident comprising one or more traffic or travel circumstances. These are linked by one or more causal relationships and apply to related locations. Each traffic or travel circumstance is represented by a SituationRecord.

Situation Record

A SituationRecord is one element of a situation. It is characterized by values at a given time, defining one version of this element. When these values change, a new version is created. One SituationRecord can be:

  • a road or traffic related event (traffic element),

  • an operator action,

  • a piece of information that is based on a non-road event,

and can contain:

  • an advisory,

  • details that impact the estimated time of arrival.

Unique identifier

Each Situation has a unique identifier. Additionally, every SituationRecord also has a unique identifier. This identifier is established when the Situation or SituationRecord is first created in the DATEX II system database. As long as the situation 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 can be made on the contents of the identifier.

The identifier is unique across all supported countries.

Validity period

A SituationRecord has a validity period comprised of:

  • a mandatory overallStartTime, which indicates the start of the SituationRecord, if it is in the past, or an expected start date, if it is in the future.

  • an optional overallEndTime, if there is an expected end date.

Impact

If the current delay is available for a SituationRecord, the delayTimeValue is provided in the Impact. If there is information about closed lanes, because of an accident or other incident, it can be populated in ImpactDetails.

In some cases there are multiple SituationRecords that are related to each other. For instance, there can be a traffic jam caused by an accident. If the locations of these SituationRecords overlap or are connected AND they have the same direction, the SituationRecords are contained in the same Situation. In that case a single Situation contains more than one SituationRecord.

It is also possible that two SituationRecords are related to each other, but do not overlap. For instance, one SituationRecord contains a diversion advice, located at a highway intersection. This is because the road is blocked farther along the segment, that is described in a different SituationRecord. In that case, the SituationPublication does not contain a reference from one SituationRecord to the other.

For the first example, consider combining the information from the SituationRecords in your end application to let the end-user know there is a delay due to an accident. In the second example, there is a diversion due to a road closure.

Language specific texts

A SituationRecord may contain language-specific text. For example, this can be a diversion advice, provided by the network manager, or some other free text. Typically, this text is available only in the language of the country.

The information is reported as a (list of) generalPublicComment element(s).

Example

<situationRecord [...] xsi:type="NetworkManagement" [...]>
    [...]
    <generalPublicComment>
        <comment>
            <value lang="DE">Wegen Reparaturarbeiten sind auf der Münchener Straße in Fahrtrichtung Benrath wechselseitig jeweils ein Fahrstreifen und der Standstreifen gesperrt.</value>
        </comment>
    </generalPublicComment>
    [...]
</situationRecord>

Location

Every SituationRecord contains a GroupOfLocations, that describes the involved location. The Location is defined in section 4.16 of the DATEX II User Guide.

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 high level and also lower level road classes that are usually not covered by TMC. The method can be used 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 implementation can be downloaded from the OpenLR website. TomTom offers support for third parties to implement and test their own implementations.

TMC (Alert-C) location referencing

The TMC feed uses Alert-C as the location referencing method. See section 4.16.5 in the DATEX II User Guide for more information. 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. Either Method2 or Method4 is used in the feed, depending on the availability of offset(s). If offset information is available, Method4 is used to identify an exact location. If the exact length of the location is available, it is provided as lengthAffected in a supplementaryPositionalDescription.

You are here