This page details the hazard data format, explaining individual Protobuf message types and providing typical examples for the various types.
Service connection instructions are found in the Platform Guide.
Additional product information is available on the TomTom Hazard Warnings page.
Data format
Data from the delivery platform is encoded in Protocol
Buffers format version 3,
described structurally through Protocol Buffers schema files.
You can access the schemas provided by TomTom in
Schema-Hazards_v1.9.0.zip.
HazardsReport
Main component of the hazards Protocol Buffers schema encapsulates
a Metadata component and HazardMessage components.
Hazard message version. New messages are assigned version 1, and subsequent updates increment the version number by 1.
Location
The location details of the hazard message are detailed in the following table.
Attribute
Data type
Description
type
LocationType
The type of location.
openlr
OpenLR
The binary OpenLR location reference with multiple encodings.
segmentIds
SegmentIds
A list of representations of the location using segment IDs of the underlying map.
coordinate
Coordinate
A single geo-coordinate in degrees according to the WGS-84 schema.
bearingInDegrees
uint32
The direction in degrees [0-360°] measured clockwise from due North.
frc
Frc
The dominant functional road class represents an order of importance for a road within the overall road network. Different map data providers use different classifications.
SegmentIds
Attribute
Data type
Description
type
ReferenceType
The ID types used to reference segments. OSM_WAY_ID is the only supported type.
segmentId
SegmentId
Sequence of SegmentIds representing the location using the specified ID type.
SegmentId
The following table outlines the attributes of the SegmentId structure, providing details on segment identification, orientation, and offsets.
Attribute
Data type
Description
id
int64
The unique identifier of the segment.
backwards
bool
True if the segment is to be interpreted in reverse.
startOffsetInMeters
int32
The offset in meters from the start of the segment.
endOffsetInMeters
int32
The offset in meters from the end of the segment.
Times
Attribute
Data type
Description
reportingTimeInEpochSeconds
uint64
First time the message was reported.
startTimeInEpochSeconds
uint64
The expected start time of the hazard.
endTimeInEpochSeconds
uint64
The expected stop time of the hazard.
Hazard
The primary component for hazards content includes mandatory attributes such as hazard category and hazard type, defining the nature of the hazard.
Additional attributes offer details on the likelihood, severity, and availability of more information regarding the hazard.
A language-dependent description of the hazard. Several languages may be supported.
lastUpdatedTimeInEpochSeconds
uint64
Last time the message was updated.
detailInformation
one of BadRoadConditionsDetailedInformation, EmergencyVehicleApproachingDetailedInformation, JamTailWarningDetailedInformation, ObjectsOnRoadDetailedInformation, ReducedVisibilityDetailedInformation, RoadworksDetailedInformation, StrongWindDetailedInformation
The severity of a hazard indicates its criticality in terms of the associated
danger.
Severity
Value
SEVERITY_UNSPECIFIED
0
CRITICAL
1
MAJOR
2
MEDIUM
3
LOW
4
DetailInformation
These are the specific properties of each type of hazard.
BadRoadConditionsDetailedInformation
Attribute
Data type
Description
isPothole
bool
True indicates that potholes cause the bad road conditions.
JamTailWarningDetailedInformation
Attribute
Data type
Description
speedAtTailInKilometersPerHours
int32
Speed at the end of the queue. A significant reduction from typical driving speed to queue-end speed is expected.
EmergencyVehicleApproachingDetailedInformation
Attribute
Data type
Description
speedInKilometersPerHour
int32
Speed of the emergency vehicle in kilometers per hour.
ObjectsOnRoadDetailedInformation
Attribute
Data type
Description
animal
bool
True if the obstacle is one or more animals. False if the obstacle is not an animal. Not available means that the service does not know whether it is an animal.
people
bool
True if the obstacle is people. False if the obstacle is not people. Not available means that the service does not know whether people are present.
ReducedVisibilityDetailedInformation
Attribute
Data type
Description
dueToFog
bool
True if the main reason for reduced visibility is fog. False if it is not due to fog. Not available if the main reason is unknown or related to a different cause.
dueToHeavyRain
bool
True, if the main reason for reduced visibility is due to heavy rain. False, if the main reason for reduced visibility is not due to heavy rain. Not available, if the main reason is not known or related to a different cause.
RoadworksDetailedInformation
Attribute
Data type
Description
lengthAffectedInMeters
int32
The length of the roadworks in meters.
currentSpeedInKilometersPerHour
uint32
The current average speed in kmh for the roadworks stretch.
laneChangesExpected
bool
Lane changes can include a reduced number of lanes, narrow lanes, or a different lane structure throughout the roadworks stretch. True if lane changes are expected. False if no lane changes are expected. Not available if it is not known whether the roadworks hazard includes lane changes.
StrongWindDetailedInformation
Attribute
Data type
Description
forHighSidedVehicles
bool
True if the strong wind hazard mainly affects high-sided vehicles. False if it affects all vehicle types. Not available means that a distinction between high-sided and other vehicles cannot be made.
Message examples
The following examples illustrate the textual representation of various hazard warning
event messages. During runtime, Protocol Buffers are transmitted in binary
form.
Example: type = ACCIDENT
1metaData {
2 expirationTimeInEpochSeconds:1743004968
3}
4message {
5 id {
6 id:"3fd6bb8e-b354-4bf8-896c-cfa766e7f185"
7 version:"1"
8}
9 location {
10 type: LINEAR
11 locationName {
12 roadName:"L1180"
13 roadNumber:"L1180"
14 fromLocation:"AS Heimsheim (A8) (L1180)"
15 toLocation:"Friolzheim (L1180)"
16}
17 openlr {
18 base64:"CwZOuCK6CRt3FvlnAQYbSNk="
19}
20 coordinate {
21 longitudeInDegrees:8.8699
22 latitudeInDegrees:48.8344
23}
24 coordinateSequence {
25 coordinateSequence {
26 longitudeInDegrees:8.8699
27 latitudeInDegrees:48.8344
28}
29 coordinateSequence {
30 longitudeInDegrees:8.85301
31 latitudeInDegrees:48.83702
32}
33}
34 frc: FRC_3
35}
36 times {
37 reportingTimeInEpochSeconds:1743002652
38 lastUpdatedTimeInEpochSeconds:1743003168
39}
40 hazard {
41 category: TRAFFIC
42 type: ACCIDENT
43 severity: MEDIUM
44 description {
45 language: DE
46 text:"Enzkreis, L1180\nzwischen Abzweig nach M\303\266nsheim und Friolzheim\nin beiden Richtungen Gefahr durch ungesicherte Unfallstelle, Gefahr durch Fahrzeugteile auf der Fahrbahn"
46 text:"B96 Berlin-Moabit, Tiergartentunnel, Kreuzberg Richtung Reinickendorf\nHeidestra\303\237e\nGefahrenstelle, Wasser auf der Fahrbahn, fahren Sie bitte besonders vorsichtig\nim Kurvenbereich der Ausfahrt Heidestra\303\237e"
47}
48 badRoadDetailInfo {
49}
50}
51}
Example: type = BROKEN_DOWN_VEHICLE
1metaData {
2 expirationTimeInEpochSeconds:1743005149
3}
4message {
5 id {
6 id:"1f11c592-c865-45f0-926a-28b232244a98"
7 version:"5"
8}
9 location {
10 type: LINEAR
11 locationName {
12 fromLocation:"Siemensstra\303\237e (L127)"
13 toLocation:"A23"
14}
15 openlr {
16 base64:"Cwa/XiZeoA4gBQC4ACwOAA=="
17}
18 coordinate {
19 longitudeInDegrees:9.48869
20 latitudeInDegrees:53.95728
21}
22 coordinateSequence {
23 coordinateSequence {
24 longitudeInDegrees:9.48869
25 latitudeInDegrees:53.95728
26}
27 coordinateSequence {
28 longitudeInDegrees:9.49053
29 latitudeInDegrees:53.95772
30}
31}
32 frc: FRC_1
33}
34 times {
35 reportingTimeInEpochSeconds:1742985000
36 endTimeInEpochSeconds:1743004800
37 lastUpdatedTimeInEpochSeconds:1743003349
38}
39 hazard {
40 category: TRAFFIC
41 type: BROKEN_DOWN_VEHICLE
42 severity: MEDIUM
43 description {
44 language: DE
45 text:"A23, Heide Richtung Hamburg, Anschlussstelle Itzehoe-Nord, Einfahrt gesperrt, Verkehrsbehinderung durch defektes Fahrzeug, Schwertransport, bis 26.03.2025 17:00 Uhr"
126 text:"Berlin-Wilmersdorf, Wexstra\303\237e\nzwischen Bundesplatz und Bernhardstra\303\237e\nf\303\274r beide Richtungen nur ein Fahrstreifen abwechselnd frei, Wasserrohrbruch, bis 30.04.2025"
127}
128}
129}
Example: type = JAM_TAIL_WARNING
1metaData {
2 expirationTimeInEpochSeconds:1743178757
3}
4message {
5 id {
6 id:"a5416a9f-a481-4880-a1a6-2dfc3e103143"
7 version:"1"
8}
9 location {
10 type: POINT
11 openlr {
12 base64:"KwbebyVH6QEWF/iT/pIBBg=="
13}
14 coordinate {
15 longitudeInDegrees:9.65936
16 latitudeInDegrees:52.42626
17}
18 bearingInDegrees:252
19 frc: FRC_0
20}
21 times {
22 reportingTimeInEpochSeconds:1743176917
23 lastUpdatedTimeInEpochSeconds:1743176957
24}
25 hazard {
26 category: TRAFFIC
27 type: JAM_TAIL_WARNING
28 severity: MAJOR
29 jamTailWarningDetailInformation {
30 speedAtTailInKilometersPerHours:20
31}
32}
33}
Example: type = OBJECTS_ON_ROAD
1metaData {
2 expirationTimeInEpochSeconds:1743005478
3}
4message {
5 id {
6 id:"bfc7b437-71f6-43ed-957c-9db011f55075"
7 version:"1"
8}
9 location {
10 type: LINEAR
11 locationName {
12 roadName:"A661"
13 roadNumber:"A661"
14 fromLocation:"Frankfurt am Main-Eckenheim (A661)"
15 toLocation:"Preungesheimer Dreieck (A661)"
16}
17 openlr {
18 base64:"CwYubSOrTwEGFQVL/kUBHw=="
19}
20 coordinate {
21 longitudeInDegrees:8.69251
22 latitudeInDegrees:50.15977
23}
24 coordinateSequence {
25 coordinateSequence {
26 longitudeInDegrees:8.69251
27 latitudeInDegrees:50.15977
28}
29 coordinateSequence {
30 longitudeInDegrees:8.70606
31 latitudeInDegrees:50.15534
32}
33}
34 frc: FRC_0
35}
36 times {
37 reportingTimeInEpochSeconds:1743000875
38 lastUpdatedTimeInEpochSeconds:1743003678
39}
40 hazard {
41 category: ROAD
42 type: OBJECTS_ON_ROAD
43 severity: MEDIUM
44 description {
45 language: DE
46 text:"A661 Bad Homburg Richtung Darmstadt zwischen Preungesheimer Dreieck und Frankfurt-Friedberger Landstra\303\237e Gefahr durch Fahrzeugteile auf der Fahrbahn"
NOTE: Usually there is a second wrong way driver message for the opposite direction.
1metaData {
2 expirationTimeInEpochSeconds:1743003858
3}
4message {
5 id {
6 id:"5cab5df4-7104-4ae4-b09d-547c80643cf0"
7 version:"1"
8}
9 location {
10 type: LINEAR
11 locationName {
12 roadName:"A2, E34"
13 roadNumber:"A2 - E34"
14 fromLocation:"Hamm-Uentrop (A2)"
15 toLocation:"B\303\266nen (A2)"
16}
17 openlr {
18 base64:"CwWq2iTC2AET0M7B5HUBF2rd+/r5AUYB"
19}
20 coordinate {
21 longitudeInDegrees:7.96975
22 latitudeInDegrees:51.69529
23}
24 coordinateSequence {
25 coordinateSequence {
26 longitudeInDegrees:7.96975
27 latitudeInDegrees:51.69529
28}
29 coordinateSequence {
30 longitudeInDegrees:7.75659
31 latitudeInDegrees:51.61191
32}
33}
34 frc: FRC_0
35}
36 times {
37 reportingTimeInEpochSeconds:1743003221
38 lastUpdatedTimeInEpochSeconds:1743003258
39}
40 hazard {
41 category: TRAFFIC
42 type: WRONG_WAY_DRIVER
43 severity: MAJOR
44 description {
45 language: DE
46 text:"A2 Hannover - Dortmund\nzwischen Hamm-Uentrop und B\303\266nen\nin beiden Richtungen Achtung, Ihnen kommt ein Falschfahrer entgegen, nicht \303\274berholen, Vorsicht auf beiden Richtungsfahrbahnen"