Driver Activity - Safety

The Driver Activity – Safety API is available for REVEAL integrated users to retrieve information related to unsafe driving behaviors captured by the GPS device.

Important concepts to understand prior to utilizing any of the available integration methods:

· Driver Activity – Safety API is offered as a RESTful web service

· Standard REST verbs are applied: GET

· Throughout this document, we will reference the unique identifier to be invoked for each of the main objects available to be created or deleted. The unique identifiers used within this API method set include:

o Driver Number

Note: The returned response will be restricted to the Reveal account's data plan. If the information being queried is outside of the data plan, a "400 Bad Request error "response will be returned.

For more details on your account's data plan please reach out to Verizon Connect Customer Support

API Summary Details

API Name	Driver Activity - Safety
Endpoint	https://fim.api.us.fleetmatics.com/da/v1/driversafety/
Operation	GET

GET Driver Safety by Driver

The GET Driver Safety API method enables the integration user to retrieve a driver’s detailed safety report for a 24 hour period.

The integration user will provide a DRIVER NUMBER and REQUEST DATE when using this method. The Driver Number is associated with a driver record in REVEAL and is unique within an account. The Request Date in the call should be a date and time stamp and 24 hours following the date and time provided will be queried.

GET Driver Safety API Request Header

Operation and Path	GET https://fim.api.us.fleetmatics.com/da/v1/driversafety/<DriverNumber>?requesteddate=<RequestDateandTime> HTTP/1.1
HOST	fim.api.us.fleetmatics.com
Accept	application/json
Authorization	Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

GET Driver Safety Sample Response

[

{

"Address": {

"AddressLine1": "I-95",

"AddressLine2": "",

"Locality": "Stuart",

"AdministrativeArea": "FL",

"PostalCode": "34997",

"Country": "USA"

"DriverNumber": "111925",

"IncidentDateTimeUtc": "2017-05-23T11:57:07",

"IncidentDurationInSeconds": 2,

"IncidentSeverity": "Moderate",

"IncidentStartingSpeedInKm": 30.600000381469727,

"IncidentType": "HardBraking",

"Latitude": 27.108964,

"Longitude": -80.25919,

"VehicleName": "WO 1087",

"VehicleNumber": "1087"

]

GET Driver Safety Count by Driver

The GET Driver Safety Count API method enables the integration user to retrieve a driver’s summary safety report for a 24 hour period. This method will not provide precise details to all safety events recorded by the driver but a count of any that occurred for the day selected.

GET Driver Safety Count API Request Header

Operation and Path	GET https://fim.api.us.fleetmatics.com/da/v1/driversafety/<DriverNumber>/counts?requesteddate=<RequestDateandTime> HTTP/1.1
HOST	fim.api.us.fleetmatics.com
Accept	application/json
Authorization	Atmosphere atmosphere_app_id=fleetmatics-p-us-[ Verizon Connect App ID ], Bearer [Authorization Token] Note: The Token API must be called in order to retrieve a valid token to provide to all subsequent calls.

GET Driver Safety Count Sample Response

{

"DriverNumber": "111925",

"IncidentDateTimeUtc": "2017-05-23T00:00:00",

"VehicleIncidentCounts": [

{

"SpeedIncidentCounts": [

{

"SpeedUpperRange": 94,

"SpeedLowerRange": 80,

"IncidentCount": 2

{

"SpeedUpperRange": 99,

"SpeedLowerRange": 95,

"IncidentCount": 1

{

"SpeedUpperRange": 109,

"SpeedLowerRange": 100,

"IncidentCount": 9

{

"SpeedUpperRange": 144,

"SpeedLowerRange": 110,

"IncidentCount": 74

{

"SpeedLowerRange": 145,

"IncidentCount": 0

}

"HardBrakeCount": 1,

"QuickStartCount": 0,

"HarshCorneringCount": 0,

"VehicleName": "WO 1087",

"VehicleNumber": "1087"

}

]

}

Field Breakdown

Field	JSON Formatted Sample	Field Notes and Default Values
Address	{ "Address": { "AddressLine1": "I-95", "AddressLine2": "", "Locality": "Stuart", "AdministrativeArea": "FL", "PostalCode": "34997", "Country": "USA" },	Address contains the global standards for address components: · Address Line 1 – location specific identification such as a house number · Address Line 2 – additional information to identify location such as an apartment number · Locality – city, town, etc. · Administrative Area – state, province, etc. · Postal Code · Country
Driver Number	"DriverNumber": "111925",	Driver Number is the unique identifier for Drivers created within REVEAL. The value will default to NULL if no Driver is Assigned to the Vehicle at the time of the GPS plot that is referenced. NULL will also be returned if the Driver record assigned at the time of the plot does not have a Driver Number associated with the record in REVEAL.
Incident Date Time UTC	"IncidentDateTimeUtc": "2017-05-23T11:57:07",	The date and time in UTC that the safety event occurred.
Incident Duration in Seconds	"IncidentDurationInSeconds": 2,	The time in seconds for the duration of the safety event. Note, not all safety incident types will show a duration in seconds.
Incident Severity	"IncidentSeverity": "Severe",	Harsh driving events recorded by REVEAL will be categorized as MODERATE or SEVERE.
Incident Starting Speed in KMPH	"IncidentStartingSpeedInKm": 30.600000381469727,	The harsh driving incident’s starting speed value in kilometers per hour.
Incident Type	"IncidentType": "HardBraking",	Incident type will be one of the following: · Hard Braking · Quick Starts · Harsh Cornering
Latitude	"Latitude": 27.108964,	The latitude coordinates for the incident location.
Longitude	"Longitude": -80.25919,	The longitude coordinates for the incident location.
Vehicle Name	"VehicleName": "WO 1087",	The Vehicle Name within REVEAL for the vehicle that reported the incident.
Vehicle Number	"VehicleNumber": "1087"	The Vehicle Number is an optional field in REVEAL. If using APIs, the Vehicle Number is often required as the vehicle’s unique identifier. However, this field can be returned as NULL.
Speed Incident Counts	"SpeedIncidentCounts": [ { "SpeedUpperRange": 94, "SpeedLowerRange": 80, "IncidentCount": 2 }, { "SpeedUpperRange": 99, "SpeedLowerRange": 95, "IncidentCount": 1 }, { "SpeedUpperRange": 109, "SpeedLowerRange": 100, "IncidentCount": 9 }, { "SpeedUpperRange": 144, "SpeedLowerRange": 110, "IncidentCount": 74 }, { "SpeedLowerRange": 145, "IncidentCount": 0 } ],	For each driver, the summary of high speeding incidents will be returned. There are 5 high speed threshold buckets that will be returned to the user. All speed threshold values are a range in kilometers per hour and coincide with REVEAL features. · Speeds between 94 and 80 kmph · Speeds between 99 and 95 kmph · Speeds between 109-100 kmph · Speeds between 144-110 kmph · Speeds above 145 kmph The Incident Count field will denote how many high speeding incidents occurred for each bucket.
Hard Brake Count	"HardBrakeCount": 1,	The total number of hard brake incidents reported by the driver for the selected 24 hour period.
Quick Start Count	"QuickStartCount": 0,	The total number of quick start incidents reported by the driver for the selected 24 hour period.
Harsh Cornering Count	"HarshCorneringCount": 0,	The total number of harsh cornering incidents reported by the driver for the selected 24 hour period.