Programming Guide to the Hours of Service Platform

Driver Statuses

The driverStatus provides real-time information from the most recent communication between the Drivers’ mobile device and Hours of Service system. This information is typically sent once per three minutes but can be sent more or less frequently as determined by the Carrier.  It is used to update the Driver’s position on a map, to show his current duty Status (OnDutyND, Driving, Sleeper, OffDuty), to pass the Driver’s available time (time remaining) until he has to take a break, in his shift, his daily driving time, and time left in his cycle. This information is then displayed on the portal in the Driver’s tab.

Fields

Tag Data Type Required Description
accountId Long No The id of the Account that owns this record.
assetId Long Yes The id of the Vehicle that the Driver used to perform the last Status change.
availableBreak Text No  Indicates the remaining time until the driver has to take a 30-minute break.
Note: Must be in seconds Duration format (PT##S). Where ## is the number of seconds (see examples)
availableCycle Text No  Indicates the remaining time until the driver has to take a Cycle Reset.
Note: Must be in seconds Duration format (PT##S). Where ## is the number of seconds (see examples)
availableDrive Text No  Indicates the remaining time until the driver has to take a stop driving.
Note: Must be in seconds Duration format (PT##S). Where ## is the number of seconds (see examples)
availableShift Text No  Indicates the remaining time until the driver has to take a Shift Reset.
Note: Must be in seconds Duration format (PT##S). Where ## is the number of seconds (see examples)
engineHours Text No Indicates the number of hours that the engine of the associated vehicle has been running.
Note: Must be in seconds Duration format (PT##S). Where ## is the number of seconds (see examples)
errorCode Integer Auto Returns an error code in the response JSON for a failing Driver Status update
errorMessage String Auto Returns an error message in the response JSON for a failing Driver Status update
eventTime Text   Indicates the date and time when the last change in status occurred.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
eventType Character (255) Yes

Indicates the last known Status of the associated Driver. Event Type can be:

  • OffDuty
  • Sleeper
  • Driving
  • OnDuty
  • WaitingAtSite
  • Remark
  • Inter
  • InterRP
  • PersonalUse
  • YardMoves
  • ClearPU
  • ClearYM
  • Certify
  • Login
  • Logout
  • PowerOn
  • PowerOnRP
  • PowerOff
  • PowerOffRP
  • MalPower
  • MalSync
  • MalTime
  • MalPos
  • MalRecord
  • MalTransfer
  • MalOther
  • MalPowerClear
  • MalSyncClear
  • MalTimeClear
  • MalPosClear
  • MalRecordClear
  • MalTransferClear
  • MalOtherClear
  • DiagPower
  • DiagSync
  • DiagMissing
  • DiagTransfer
  • DiagUnidentified
  • DiagOther
  • DiagPowerClear
  • DiagSyncClear
  • DiagMissingClear
  • DiagTransferClear
  • DiagUnidentifiedClear
  • DiagOtherClear
fuelLevel Double (between 0.0 and 100.0) No Indicates the fuel level percentage during the last known Status of the associated Driver
gainTimeHowMuch Text No Indicates the amount of time the associated User will gain.
Note: Must be in seconds Duration format (PT##S). Where ## is the number of seconds (see examples)
gainTimeHowMuchNextDay Text No  Indicates the amount of time the associated User will gain for the next day.
Note: Must be in seconds Duration format (PT##S). Where ## is the number of seconds (see examples)
gainTimeWhen Text No  Indicates when the associated User will gain time.
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
gainTimeWhich Character (255) No  Indicates the type of time that the associated User will gain
gpsSource Character (255) No  The GPS source of the Driver during this status. Can be any of the following values:

  • MOBILE_DEVICE
  • VBUS_DEVICE
  • EITHER_DEVICE
heading Integer (between 0 and 360) No Indicates the heading in degrees during the last known Status of the associated Driver
id Auto-incremented Long Auto  Unique identifier
lastChangedDate Text Auto  Auto-generated timestamp of the last change made to this record
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
latitude Double Precision No  Indicates the latitude coordinate of the location where the Driver was last tracked.
location Character (255) No  Contains the address of the location where the Driver was last tracked.
longitude Double Precision No  Indicates the longitude coordinate of the location where the Driver was last tracked.
mobileOSVersion Character (255) No  Information for the OS version of the device used to record the last Status of the Driver.
name Character (255) No  The name of the Driver.
nextViolation Character (255) No  The next Violation the Driver will be getting if the Driver is currently driving, otherwise this is not returned.
nextViolationTimestamp Text No  Information for the time remaining until the next Violation if the driver is currently driving, otherwise this is not returned.
odometerKm Double Precision No The Odometer of the Vehicle during the last Status of the Driver
softwareVersion Character (255) No  Information for App version used to record the last Status of the Driver.
speedKph Double Precision No  The speed of the Vehicle during the last Status of the Driver. 
subsetId Long Auto Indicates the Subset of the Terminal where the Driver is assigned
terminalId Long Auto Id of the Terminal where the Driver is assigned
uncertifiedLogs Integer No The number of uncertified Driver Daily logs the User has during his/her latest Driver Status. This is only returned on GET.
userId Long No The id of the Driver that is tied to this status.
vbusConnected Boolean No  Indicates whether or not the Vehicle was connected to the VBUS device when the event occurred.
vehiclePowerOn Boolean No  Indicates whether or not the Vehicle was powered on when the event occurred

Read

API PATH: /api/v2/driverStatuses
METHOD: GET
PARAMETERS: user-id – Retrieves matching records for a specific User (e.g. user-id=496650, current User by default)
asset-id – Retrieves matching records for a specific asset (e.g. asset-id=1321545, current asset by default)
asset.name – Retrieves matching records for a specific asset name (e.g. asset.name=Vehicle 1, all Vehicles by default)
terminal-id – Retrieves matching records of Drivers assigned to the specified Terminal (e.g. terminal-id=255, all Terminals by default)
subset-id – Retrieves matching records whose subsetId of the Driver matches the specified parameter (e.g. subset-id=940, returns drivers from all subsets by default)
active – Retrieves matching records depending on the boolean value specified. (e.g. active=true)
  If true, only statuses of active Drivers are retrieved.
  If false, only statuses of inactive Drivers are retrieved.
  If parameter is not included or null, Driver Statuses of all Drivers are retrieved.
system – Retrieves matching records based on Driver type, depending on the boolean value specified. (e.g. system=true, false by default) 
   If true, only the unidentifiedDriver’s Status is retrieved.
   If false, only actual Drivers’ Statuses are retrieved.
   Wild-carding using system=* or system=true,false will retrieve all Driver Statuses
offset – Retrieves matching records after an offset value (e.g. offset=2)
limit – Retrieves a number of records per page specified by the value (e.g. limit=10)
SORTING:

sort=id – Sort records by their id field in ascending order (DEFAULT)
sort=-id – Sort records by their id field in descending order
sort=user-id – Sort records by their userId field in ascending order
sort=-user-id – Sort records by their userId field in descending order
sort=asset-id – Sort records by their assetId field in ascending order
sort=-asset-id – Sort records by their assetId field in descending order
sort=asset-name – Sort records by asset name in ascending order
sort=-asset-name – Sort records by asset name in descending order
sort=event-time – Sort records by their eventTime field in ascending order
sort=-event-time – Sort records by their eventTime field in descending order
sort=event-type – Sort records by their eventType field in ascending order
sort=-event-type – Sort records by their eventType field in descending order
sort=available-cycle – Sort records by their availableCycle field in ascending order
sort=-available-cycle – Sort records by their availableCycle field in descending order
sort=available-shift – Sort records by their availableShift field in ascending order
sort=-available-shift – Sort records by their availableShift field in descending order
sort=available-drive – Sort records by their availableDrive field in ascending order
sort=-available-drive – Sort records by their availableDrive field in descending order
sort=software-version – Sort records by their softwareVersion field in ascending order
sort=-software-version – Sort records by their softwareVersion field in descending order
sort=next-violation-timestamp – Sort records by their nextViolationTimestamp field in ascending order
sort=-next-violation-timestamp – Sort records by their nextViolationTimestamp field in descending order
sort=uncertified-logs – Sort records by their uncertifiedLogs field in ascending order
sort=-uncertified-logs – Sort records by their uncertifiedLogs field in descending order
sort=last-changed-date – Sort records by their last change date field in ascending order
sort=-last-changed-date – Sort records by their last change date field in descending order
QUERY STRING EXAMPLES: Get the Driver Status with the specified id: api/v2/driverStatuses/2699
Get all Driver Statuses for the multiple authenticated Users : ?user-id=1250941,1250887
Get all Driver Statuses for the authenticated User with a specific Asset : ?user-id=1250941&asset-id=1321334
Get two Driver Statuses of the current Account with an offset of 1 : ?offset=1&limit=2
Get all Driver Statuses of the current Account sorted by event type alphabetically: ?sort=event-type
EXAMPLE RESPONSE: 
[
  {
    "assetId": 1328277,
    "availableCycle": "PT251053S",
    "availableDrive": "PT39133S",
    "availableShift": "PT49393S",
    "eventTime": "2018-06-11T01:50:00.000Z",
    "eventType": "Driving",
    "fuelLevel": 50.0,
    "gainTimeHowMuch": "PT39600S",
    "gainTimeHowMuchNextDay": "PT39600S",
    "gainTimeWhen": "2018-06-11T11:50:46.146Z",
    "gainTimeWhich": "Shift Reset",
    "gpsSource": "VBUS_DEVICE",
    "heading" 100,
    "availableBreak": "PT27793S",
    "latitude": 41.979829,
    "location": "2mi NW Schiller Park, IL",
    "longitude": -87.898291,
    "mobileOSVersion": "5.1.1",
    "name": "John Doe",
    "nextViolation": "Driving Hours Before 30 Minute Break",
    "nextViolationTimestamp": "2018-06-11T09:34:00.000Z",
    "odometerKm": 10.0,
    "softwareVersion": "1.0.1623.6194",
    "speedKph": 138.166,
    "terminalId": 110,
    "subsetId": 940,
    "uncertifiedLogs": 4,
    "userId": 1253147,
    "vbusConnected": false,
    "vehiclePowerOn": true,
    "engineHours": "PT5400S",
    "accountId": 1248653,
    "id": 2699,
    "lastChangedDate": "2018-06-11T01:46:56.864Z"
  }
]

Create

API PATH: /api/v2/driverStatuses
METHOD: POST
EXAMPLE REQUEST: 
[
  {
    "assetId": 1328277,
    "availableCycle": "PT251053S",
    "availableDrive": "PT39133S",
    "availableShift": "PT49393S",
    "eventTime": "2018-06-11T01:50:00.000Z",
    "eventType": "Driving",
    "fuelLevel": 50.0,
    "gainTimeHowMuch": "PT39600S",
    "gainTimeHowMuchNextDay": "PT39600S",
    "gainTimeWhen": "2018-06-11T11:50:46.146Z",
    "gainTimeWhich": "Shift Reset",
    "gpsSource": "VBUS_DEVICE",
    "heading" 100,
    "availableBreak": "PT27793S",
    "latitude": 41.979829,
    "location": "2mi NW Schiller Park, IL",
    "longitude": -87.898291,
    "mobileOSVersion": "5.1.1",
    "name": "John Doe",
    "nextViolation": "Driving Hours Before 30 Minute Break",
    "nextViolationTimestamp": "2018-06-11T09:34:00.000Z",
    "odometerKm": 10.0,
    "softwareVersion": "1.0.1623.6194",
    "speedKph": 138.166,
    "userId": 1253147,
    "vbusConnected": false,
    "vehiclePowerOn": true,
    "engineHours": "PT5400S"
  }
]
EXAMPLE RESPONSE: 
[
  {
    "assetId": 1328277,
    "availableCycle": "PT251053S",
    "availableDrive": "PT39133S",
    "availableShift": "PT49393S",
    "eventTime": "2018-06-11T01:50:00.000Z",
    "eventType": "Driving",
    "fuelLevel": 50.0,
    "gainTimeHowMuch": "PT39600S",
    "gainTimeHowMuchNextDay": "PT39600S",
    "gainTimeWhen": "2018-06-11T11:50:46.146Z",
    "gainTimeWhich": "Shift Reset",
    "gpsSource": "VBUS_DEVICE",
    "heading" 100,
    "availableBreak": "PT27793S",
    "latitude": 41.979829,
    "location": "2mi NW Schiller Park, IL",
    "longitude": -87.898291,
    "mobileOSVersion": "5.1.1",
    "name": "John Doe",
    "nextViolation": "Driving Hours Before 30 Minute Break",
    "nextViolationTimestamp": "2018-06-11T09:34:00.000Z",
    "odometerKm": 10.0,
    "softwareVersion": "1.0.1623.6194",
    "speedKph": 138.166,
    "terminalId": 110,
    "subsetId": 940,
    "uncertifiedLogs": 4,
    "userId": 1253147,
    "vbusConnected": false,
    "vehiclePowerOn": true,
    "engineHours": "PT5400S",
    "accountId": 1248653,
    "id": 2699,
    "lastChangedDate": "2018-06-11T01:46:56.864Z"
  }
]

Update

API PATH: /api/v2/driverStatuses
METHOD: PUT
EXAMPLE REQUEST: 
[
  {
    "assetId": 1328277,
    "availableCycle": "PT251053S",
    "availableDrive": "PT39133S",
    "availableShift": "PT49393S",
    "eventTime": "2018-06-11T01:50:00.000Z",
    "eventType": "Driving",
    "fuelLevel": 50.0,
    "gainTimeHowMuch": "PT39600S",
    "gainTimeHowMuchNextDay": "PT39600S",
    "gainTimeWhen": "2018-06-11T11:50:46.146Z",
    "gainTimeWhich": "Shift Reset",
    "gpsSource": "VBUS_DEVICE",
    "heading" 100,
    "availableBreak": "PT27793S",
    "latitude": 41.979829,
    "location": "2mi NW Schiller Park, IL",
    "longitude": -87.898291,
    "mobileOSVersion": "5.1.1",
    "name": "John Doe",
    "nextViolation": "Driving Hours Before 30 Minute Break",
    "nextViolationTimestamp": "2018-06-11T09:34:00.000Z",
    "odometerKm": 10.0,
    "softwareVersion": "1.0.1623.6194",
    "speedKph": 138.166,
    "userId": 1253147,
    "vbusConnected": false,
    "vehiclePowerOn": true,
    "engineHours": "PT5400S",
    "id": 2699
  }
]
EXAMPLE RESPONSE: 
[
  {
    "assetId": 1328277,
    "availableCycle": "PT251053S",
    "availableDrive": "PT39133S",
    "availableShift": "PT49393S",
    "eventTime": "2018-06-11T01:50:00.000Z",
    "eventType": "Driving",
    "fuelLevel": 50.0,
    "gainTimeHowMuch": "PT39600S",
    "gainTimeHowMuchNextDay": "PT39600S",
    "gainTimeWhen": "2018-06-11T11:50:46.146Z",
    "gainTimeWhich": "Shift Reset",
    "gpsSource": "VBUS_DEVICE",
    "heading" 100,
    "availableBreak": "PT27793S",
    "latitude": 41.979829,
    "location": "2mi NW Schiller Park, IL",
    "longitude": -87.898291,
    "mobileOSVersion": "5.1.1",
    "name": "John Doe",
    "nextViolation": "Driving Hours Before 30 Minute Break",
    "nextViolationTimestamp": "2018-06-11T09:34:00.000Z",
    "odometerKm": 10.0,
    "softwareVersion": "1.0.1623.6194",
    "speedKph": 138.166,
    "terminalId": 110,
    "subsetId": 940,
    "uncertifiedLogs": 4,
    "userId": 1253147,
    "vbusConnected": false,
    "vehiclePowerOn": true,
    "engineHours": "PT5400S",
    "accountId": 1248653,
    "id": 2699,
    "lastChangedDate": "2018-06-11T01:46:56.864Z"
  }
]

Driver Status Archives

API PATH: /api/v2/driverStatuses/archive
METHOD: GET
PARAMETERS: user-id – Retrieves matching records for a specific User (e.g. user-id=496650, current User by default) 
asset-id – Retrieves matching records for a specific asset (e.g. asset-id=1321545, current asset by default)
asset.name – Retrieves matching records for a specific asset name (e.g. asset.name=Vehicle 1, all Vehicles by default)
terminal-id – Retrieves matching records of Drivers assigned to the specified Terminal (e.g. terminal-id=255, all Terminals by default)
subset-id – Retrieves matching records whose subsetId of the Driver matches the specified parameter (e.g. subset-id=940, returns drivers from all subsets by default) 
active – Retrieves matching records depending on the boolean value specified. (e.g. active=true)
  If true, only statuses of active Drivers are retrieved.
  If false, only statuses of inactive Drivers are retrieved.
  If parameter is not included or null, Driver Statuses of all Drivers are retrieved.
system – Retrieves matching records based on Driver type, depending on the boolean value specified. (e.g. system=true, false by default) 
   If true, only the unidentifiedDriver’s Status is retrieved. 
   If false, only actual Drivers’ Statuses are retrieved. 
   Wild-carding using system=* or system=true,false will retrieve all Driver Statuses
offset – Retrieves matching records after an offset value (e.g. offset=2)
limit – Retrieves a number of records per page specified by the value (e.g. limit=10)
from-event-time – Retrieves matching records that occurred on or after the specified date (e.g. from-event-time=2016-07-05T03:03:10.147Z, all dates by default)
to-event-time – Retrieves matching records that occurred on or before the specified date (e.g. to-event-time=2016-07-05T03:03:10.147Z, all dates by default)
EXAMPLE RESPONSE: 
[
  {
    "assetId": 1312920,
    "availableCycle": "PT-242592S",
    "availableDrive": "PT-487392S",
    "availableShift": "PT-472992S",
    "eventTime": "2018-06-22T00:33:54.656Z",
    "eventType": "Driving",
    "fuelLevel": 0,
    "gainTimeHowMuch": "PT-242592S",
    "gainTimeHowMuchNextDay": "PT-242592S",
    "gainTimeWhen": "2018-06-28T13:57:06.904Z",
    "gainTimeWhich": "Shift Reset",
    "gpsSource": "MOBILE_DEVICE",
    "heading": 0,
    "latitude": -33.8688183333333,
    "location": "10878mi WNW St. John's, NL",
    "longitude": 151.209295,
    "mobileOSVersion": "4.4.4",
    "name": "Ian Support",
    "odometerKm": 0,
    "softwareVersion": "1.0.1805.14593",
    "speedKph": 0,
    "terminalId": 1419,
    "uncertifiedLogs": 210,
    "userId": 1346433,
    "vbusConnected": false,
    "vehiclePowerOn": false,
    "engineHours": "PT5400S",
    "accountId": 40,
    "id": 274178985,
    "lastChangedDate": "2018-06-28T03:57:10.660Z",
    "speedKm": 0
  }
]
 

Stats

API PATH: /api/v2/stats/driverStatuses
METHOD: GET
PARAMETERS: user-id – counts records for the specified Users
asset-id – counts records for a specified Asset 
terminal-id – counts records for Drivers assigned to the specified Terminal
active – counts records depending on active or inactive Drivers
EXAMPLE RESPONSE: 
{
  "Event Type Totals":
    {
      "Drving": 2
      "OnDuty": 1,
      "OffDuty": 3,
      "Sleeper": 1      
    }
}

API error calls

ERROR MESSAGE POSSIBLE CAUSES
POST is not supported. POST method is not allowed for /stats
Driver Status should have an assetId POST error because Driver Status doesn’t have a value for assetId
PUT is not supported. PUT method is not allowed for /stats
DELETE is not supported. DELETE method is not allowed for Driver Status and /stats