Get Safety Messages

Service version: 1
Last edit: 2022.08.25

Purpose

You can use this endpoint to query for recent safety-related messages detected by TomTom applications. The response will contain events that occurred within a specific and recent time period of up to 24 hours.

Request data

HTTPS method: GET

  • Constants and parameters enclosed in curly brackets &#123 } 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.

URL format

https://{baseURL}/srti/{versionNumber}?key={Your_API_Key}

curl command format

curl -XGET 'https://{baseURL}/srti/{versionNumber}?key={Your_API_Key}&age={maxAge}' -H 'accept:{contentFormat}'

Request example

curl 'https://api.tomtom.com/srti/1?key={Your_API_Key}&age=PT30m' -H 'accept:application/octet-stream' -o srti.out

Request parameters

The following table describes the parameters that can be used in a request.

  • Required parameters must be used or the call will fail.
  • Optional parameters may be used.
  • The order of request parameters is not important.

Required parameters

Parameter

Description

baseURL
string

Base URL for calling the API.


Value: api.tomtom.com

versionNumber
string

Service version.


Value: The current value is 1.

key
string

An API Key valid for the requested service. Use the "Request Access" button to get an API Key.


Value: Your valid API Key.

Optional parameters

Parameter

Description

contentFormat
string

Users can influence the output format of the content using the standard HTTP

"Accept" header

. Possible value are:

  • text/plain - (default) delivers a textual representation of the content

  • application/octet-stream - delivers the content in protobuf binary format

age
string

This parameter limits the number of delivered events by maximum age. The value format follows the specification of

ISO standard 8601 for Durations

.

  • For example, the value of "PT1H" describes the period of one hour. The service will deliver only messages with an event time within this period before "now", the moment of the call.

  • The default maximum age is 24 hours. It automatically applies when the age parameter is omitted. This value also cannot be further extended with a bigger value for age.

Response data

Response body

The data is delivered in binary or human-readable format controlled by the specified HTTP accept header. The schema of the data is structured in either case according to the Sensoris 1.3 format. Human-readable output helps to evaluate the serves. Programmatic solutions potentially will use the Protobuf out output. Please find details on the Sensoris format, as well as the proto schema files to decode the protobuf on this website: sensoris.org.

For convenience the following command shows how to decode a TomTom SRTI response via the command line using the Sensoris proto schema and the standard Protocol Buffers command line client.

protoc --decode sensoris.protobuf.messages.data.DataMessages ./sensoris/protobuf/messages/data.proto < srti-response.pb

Please find the following exemplary response in Sensoris text format showing two data messages.

  • A detection of a broken down vehicle.
  • A generic hazard detection. This one has no concrete type attribute. It's reflects a hazardous situation detected not specifying or not matching any of the available types.

Response body - Sensoris

1data_message {
2 envelope {
3 ids {
4 session_id {
5 value: "1afba655-e81c-44f5-82ac-d33010bc6398"
6 }
7 }
8 }
9 event_group {
10 localization_category {
11 vehicle_position_and_orientation {
12 envelope {
13 timestamp {
14 posix_time {
15 value: 1657100527000
16 }
17 }
18 }
19 position_and_accuracy {
20 geographic_wgs84 {
21 longitude {
22 value: 436102000
23 }
24 latitude {
25 value: 5187591500
26 }
27 }
28 }
29 }
30 }
31 traffic_events_category {
32 hazard {
33 envelope {
34 timestamp {
35 posix_time {
36 value: 1657100527000
37 }
38 }
39 }
40 type_and_confidence {
41 type: BROKEN_DOWN_VEHICLE
42 }
43 }
44 }
45 }
46}
47data_message {
48 envelope {
49 ids {
50 session_id {
51 value: "709f08d5-1434-4c38-adb1-f6cb940db8e1"
52 }
53 }
54 }
55 event_group {
56 localization_category {
57 vehicle_position_and_orientation {
58 envelope {
59 timestamp {
60 posix_time {
61 value: 1656928028000
62 }
63 }
64 }
65 position_and_accuracy {
66 geographic_wgs84 {
67 longitude {
68 value: 1332214400
69 }
70 latitude {
71 value: 5253750200
72 }
73 }
74 }
75 }
76 vehicle_position_and_orientation {
77 envelope {
78 timestamp {
79 posix_time {
80 value: 1656928029000
81 }
82 }
83 }
84 position_and_accuracy {
85 geographic_wgs84 {
86 longitude {
87 value: 1332187500
88 }
89 latitude {
90 value: 5253745600
91 }
92 }
93 }
94 }
95 }
96 traffic_events_category {
97 hazard {
98 envelope {
99 timestamp {
100 posix_time {
101 value: 1656928029000
102 }
103 }
104 }
105 type_and_confidence {
106 }
107 }
108 }
109 }
110}

Response fields

For the detailed description of the data elements of the response messages, please consult the Sensoris specification.

On a structural level, a data message contains a sequence of vehicle_position_and_orientation elements and the actual event in the form of an element of the traffic_events_category. The positions describe the path leading to the location of the event. They can be used to derive the direction and location that the traffic event relates to.

The traffic event describes some attributes of the situation itself. The most minimal is the unspecified hazard which is represented by the pure existence of the hazard element.

Response headers

The following data table contains response headers sent back from an API server.

Header

Description

Content-Type

Indicates the format of the response as chosen by the client. Format: type/subtype; charset=utf-8


Value: type/subtype is one of:

  • text/plain - delivers a textual representation of the content

  • application/octet-stream - delivers the content in protobuf binary format

Tracking-ID

An identifier for the request. If the Tracking-ID header was specified, it is replicated in the response. Otherwise, it is generated automatically by the service. It is only meant to be used for support and does not involve tracking of you or your users in any form.


Value: An identifier for the request.

Error response

In case of an unsuccessful response the server will indicate the problem by use of an appropriate HTTP response code. The response body can, in addition, provide further context information in human-readable form.