Get Safety Messages
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 { } 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 |
string | Base URL for calling the API. Value: api.tomtom.com |
string | Service version. Value: The current value is |
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 |
string | Users can influence the output format of the content using the standard HTTP "Accept" header. Possible value are:
|
string | This parameter limits the number of delivered events by maximum age. The value format follows the specification of ISO standard 8601 for Durations.
|
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: 165710052700016 }17 }18 }19 position_and_accuracy {20 geographic_wgs84 {21 longitude {22 value: 43610200023 }24 latitude {25 value: 518759150026 }27 }28 }29 }30 }31 traffic_events_category {32 hazard {33 envelope {34 timestamp {35 posix_time {36 value: 165710052700037 }38 }39 }40 type_and_confidence {41 type: BROKEN_DOWN_VEHICLE42 }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: 165692802800062 }63 }64 }65 position_and_accuracy {66 geographic_wgs84 {67 longitude {68 value: 133221440069 }70 latitude {71 value: 525375020072 }73 }74 }75 }76 vehicle_position_and_orientation {77 envelope {78 timestamp {79 posix_time {80 value: 165692802900081 }82 }83 }84 position_and_accuracy {85 geographic_wgs84 {86 longitude {87 value: 133218750088 }89 latitude {90 value: 525374560091 }92 }93 }94 }95 }96 traffic_events_category {97 hazard {98 envelope {99 timestamp {100 posix_time {101 value: 1656928029000102 }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 |
---|---|
Indicates the format of the response as chosen by the client. Format:
Value:
| |
Tracking-ID | An Value: An |
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.