Traffic Incidents - DATEX II
Purpose
The TomTom Traffic Incidents - Intermediate Service – DATEX II endpoint (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 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.
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.
Information on specific events on road regulations due to COVID-19 are found in the FAQs.
Scope
This document gives basic information on the Service and shows how to configure it 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).
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 DATEX II event, and we add an Alert-C event code with the same meaning. This Alert-C event code allows the user to customize the content at their own discretion. 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 DATEX II can be found in the following section, Standard information.
Optional configurations
The Service provides users traffic incident data with a highly customizable optional configuration, in addition to the standard configuration.
Detailed information about the physical representation in DATEX II can be found in the following section, Optional information.
Option | Description |
---|---|
Incident end time | This option predicts the expected ending time for the traffic incident such as the expected end time of a jam or a closure. |
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 the location referencing method OpenLR. |
HOV jams | Selecting this option provides the user with high-occupancy vehicle (HOV) jams information. This feature is only available in combination with the 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 options provides the names and versions of the maps that were used to create the content. |
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.
'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 the DATEX II payload specification for the links to the documents). TomTom does not support the SOAP envelope as described in the Software Developers Guide.
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.
How do you make a request?
To make a request, the URL should be constructed as shown in the following sections.
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 as follows:
https://{baseURL}/tsq/hdt/{productName}/{apiKey}/content.xml
The following is an example URL:
https://cert-traffic.tomtom.com/tsq/hdt/DEU-HDT-OPENLR/{Your_API_Key}/content.xml
The following is an example cURL:
curl --compressed -XGET 'https://cert-traffic.tomtom.com/tsq/hdt/DEU-HDT-OPENLR/{Your_API_Key}/content.xml'
Request parameters
The following table provides a detailed explanation of the available fields that were previously
shown in the HTTPS Method: GET
section.
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), type of feed (HDT is the incident feed), and the
location referencing method (TMC or OpenLR). |
| Authorization key for access to the API. |
Request 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.
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 FAQ for that topic.
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
This is a response you receive after a request is made. If you make the following request:
https://cert-traffic.tomtom.com/tsq/hdt/DEU-HDT-OPENLR/{Your_API_Key}/content.xml
You can expect the following response:
1<?xml version="1.0" encoding="UTF-8"?>2<d2LogicalModel modelBaseVersion="1.0">3 <exchange>4 <supplierIdentification>5 <country>nl</country>6 <nationalIdentifier>TomTom Traffic Service</nationalIdentifier>7 </supplierIdentification>8 </exchange>9 <payloadPublication xsi:type="SituationPublication" lang="en">10 <publicationTime>2015-12-14T12:09:03Z</publicationTime>11 <publicationCreator>12 <country>other</country>13 <nationalIdentifier>a557f357-4196-4f7f-8002-8c8aa0e18193</nationalIdentifier>14 </publicationCreator>15 <situation id="TTI-a557f357-4196-4f7f-8002-8c8aa0e18193-TTL119738232499376">16 <headerInformation>17 <confidentiality>internalUse</confidentiality>18 <informationStatus>real</informationStatus>19 <urgency>urgent</urgency>20 </headerInformation>21 <situationRecord xsi:type="AbnormalTraffic" id="TTI-a557f357-4196-4f7f-8002-8c8aa0e18193-TTL119738232499376-1">22 <situationRecordCreationTime>2015-12-14T12:09:03Z</situationRecordCreationTime>23 <situationRecordVersion>1</situationRecordVersion>24 <situationRecordVersionTime>2015-12-14T12:09:03Z</situationRecordVersionTime>25 <situationRecordFirstSupplierVersionTime>2015-12-14T12:09:03Z</situationRecordFirstSupplierVersionTime>26 <probabilityOfOccurrence>probable</probabilityOfOccurrence>27 <validity>28 <validityStatus>definedByValidityTimeSpec</validityStatus>29 <validityTimeSpecification>30 <overallStartTime>2015-12-14T12:09:03Z</overallStartTime>31 <overallEndTime>2015-12-14T12:29:03Z</overallEndTime>32 </validityTimeSpecification>33 </validity>34 <impact>35 <delays>36 <delayTimeValue>94.0</delayTimeValue>37 </delays>38 </impact>39 <groupOfLocations>40 <locationContainedInGroup xsi:type="Linear">41 <locationExtension>42 <openlr>43 <binary version="3">CweksCU8dxt9DP8AAmQcSRE=</binary>44 </openlr>45 </locationExtension>46 </locationContainedInGroup>47 </groupOfLocations>48 <situationRecordExtension>49 <alertCEventCode>115</alertCEventCode>50 </situationRecordExtension>51 <abnormalTrafficType>slowTraffic</abnormalTrafficType>52 <trafficTrendType>trafficBuildingUp</trafficTrendType>53 <abnormalTrafficExtension>54 <averageSpeed>18.0</averageSpeed>55 </abnormalTrafficExtension>56 </situationRecord>57 </situation>5859[...]6061 </payloadPublication>62</d2LogicalModel>
Response – DATEX II payload specification (analysis of the received output)
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. Recommended documents are:
- DATEX II v1.0 User Guide version 1.0 ( DATEXIIv1.0-UserGuide_v1.0.pdf )
- DATEX II v1.0 Software Developers Guide version 1.0 ( DATEXIIv1.0-DevGuide_v1.0.pdf )
- DATEX II v1.0 Exchange Platform Specific Model version 1.0 ( DATEXIIv1.0-ExchangePSM_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.
Important: XSD schema
TomTom extended the data model with additional fields; the full XSD schema including extensions can be downloaded by clicking this Level B extension. 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).
How the data is organized
Situation publication
The traffic information is provided as a SituationPublication
. A SituationPublication
is the
snapshot of the latest traffic data. A SituationPublication
can contain several different
situations.
The service does not support a delta mechanism. Therefore, incremental updates are not possible.
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 should be made about the identifier.
The identifier is unique across all supported countries.
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.
Related situation records
In some cases, there are multiple SituationRecords
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
SituationRecords
overlap or are connected AND they occur in the same direction, then the
SituationRecords
are contained in the same Situation
. In that case, a single Situation
contains
more than one SituationRecord
.
Sometimes, it is 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.
Since 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.
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).
Feature | Example | ||||
---|---|---|---|---|---|
Validity period
|
| ||||
Location | only OpenLR:
only TMC:
TMC + OpenLR:
| ||||
Average speed for jams
|
| ||||
Delay for jams
|
| ||||
Alert-C event codes
| Refer to ISO TS 14819-2 at https://www.iso.org for Alert-C codes and conventions.
| ||||
Language specific texts
|
| ||||
Probability of occurrence
|
|
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.
Feature | Example | ||||
---|---|---|---|---|---|
Incident end time
|
| ||||
Jam tendency
|
| ||||
Weather-related messages
| |||||
Jam ahead warnings
|
| ||||
Average speed for journalistic events
| Example of a
All other extension types listed on the left work the same way as | ||||
Turn-dependent jams
|
| ||||
HOV jams
|
| ||||
Incident node name
|
| ||||
Road number
| Example for the German freeway (Autobahn) A3:
| ||||
Future incidents
|
| ||||
Map version
|
|