Programming Guide to the Hours of Service Platform

VBUS Data

VBUS Data is data collected from a Vehicle’s engine bus and is associated with the Asset record of the Vehicle. These values that have values are as they are reported by the Vehicle Bus. Reporting of values are dependent on both the Vehicle make and model, as well as the reporting VBUS Device. Most Vehicles and Devices do not report all parameters listed.

Fields

Tag Data Type Required Description
accountId Long No The id of the Account that owns this record.
assetId Long Yes ID of Asset that reported this data
batteryVoltage Double Precision No Battery Voltage
driverHistoryId Long No ID of Driver History associated with this data
engineCoolantTemperature Double Precision No Engine Coolant Temperature
engineOilPressure Double Precision No Engine Oil Pressure
engineSpeedRpm Double Precision No Engine Speed (RPM)
engineTotalHours Double Precision No Total Engine Hours
fuelEconomy Double Precision No Fuel Economy
fuelLevel Double Precision No Fuel level remaining of Vehicle
fuelRate Integer No Fuel Rate
gpsSource Text No The GPS Source of this VBUS Data. Can be any of the following values:

  • MOBILE_DEVICE
  • VBUS_DEVICE
  • EITHER_DEVICE
hdop Double Precision No Horizontal dilution of precision
highResOdometerKm Double Precision No Odometer (high-resolution)
id Auto-incremented Long Auto Unique Identifier
idleFuelConsumed Integer No Fuel consumed by vehicle while on idle
ignition Integer No Ignition State
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 Latitude of the vehicle when the data was collected.
longitude Double Precision No Longitude of the vehicle when the data was collected.
numSatellites Integer No Number of Satellites
odometerKm Double Precision No Odometer
parkingBrake Integer No Parking Brake Status
ptoStatus Integer No PTO Status Indicator
seatBelt Integer No Seatbelt Status
state Character (50) No The state the Asset was in when the data was collected. Can either be one of the following state codes:

  • USA: AL, AK, AR, AZ, CA, CO, CT, DC, DE, FL, GA, HI, ID, IL, IN, IA, KS, KY, LA, ME, MD, MA, MI, MN, MS, MO, MT, NE, NV, NH, NJ, NM, NY, NC, ND, OH, OK, OR, PA, RI, SC, SD, TN, TX, UT, VT, VA, WA, WV, WI, WY
  • USA Protectorates: AS, DC, GU, MP, PR, VI
  • Canada: AB, BC, MB, NB, NF, NS, NT, ON, PE, QC, SK, YT
  • Mexico: MEX_AG, MEX_BN, MEX_BS, MEX_CH, MEX_CI, MEX_CL, MEX_CP, MEX_CS, MEX_DF, MEX_DG, MEX_GE, MEX_GJ, MEX_HD, MEX_JA, MEX_MC, MEX_MR, MEX_MX, MEX_NA, MEX_NL, MEX_OA, MEX_PU, MEX_QE, MEX_QI, MEX_SI, MEX_SL, MEX_SO, MEX_TA, MEX_TB, MEX_TL, MEX_VC, MEX_YU, MEX_ZA
throttle Double Precision No Throttle Position
timestamp Text No Date and time the data was collected
Note: Format is in timestamp and timezone (YYYY-MM-DDTHH:MM:SS.sssZ, e.g: 1970-01-01T00:00:00.000Z)
totalEngineHours Double Precision No Total Engine Hours
totalFuelUsed Double Precision No Total Fuel Used
transCurrentGear Integer  No Current Transmission Gear
tripOdometerKm Double Precision  No Trip Odometer
userId Long No ID of User associated with this data
vehicleSpeedKph Double Precision  No Vehicle Ground Speed
vin Text (unlimited) No Vehicle Identification Number

Read

API PATH: /api/v2/vbusData
METHOD: GET
PARAMETERS: asset-id – Retrieves matching records with the specified Asset id (e.g. asset-id=1324556, all Assets by default)
user-id – Retrieves matching records with the specified User id (e.g. user-id=1252733, all Users by default)
driver-history-id – Retrieves matching records with the specified Driver History id (e.g. driver-history-id=5112165, all Driver Histories by default)
from-timestamp – Retrieves matching records with the timestamp on or after the the timestamp given (e.g. from-timestamp=2016-10-18T04:14:13.310Z, all timestamps by default)
to-timestamp – Retrieves matching records with the timestamp before the the timestamp given (e.g. to-timestamp=2016-10-18T04:14:13.310Z, all timestamps by default)
offset – Retrieves matching records after an offset value (e.g. offset=2, zero offset by default)
limit – Retrieves a number of records per page specified by the value (e.g. limit=10, all records by default)
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=asset-id – Sort records by their assetId field in ascending order
sort=-asset-id – Sort records by their assetId field in descending order
sort=timestamp – Sort records by their timestamp in ascending order
sort=-timestamp – Sort records by their timestamp field in descending order
sort=user-id – Sort records by their userId in ascending order
sort=-user-id – Sort records by their userId field in descending order
QUERY STRING EXAMPLES: Get the VBUS Data with the specified id: api/v2/vbusData/162171
Get two VBUS Data of the current Account with an offset of 1 : ?offset=1&limit=2
Get all VBUS Data of the current Account sorted by timestamp: ?sort=timestamp
EXAMPLE RESPONSE: 
[
  {
    "assetId": 1324556,
    "timestamp": "2018-06-11T12:00:00.000Z",
    "batteryVoltage": 1.5,
    "engineOilPressure": 28.0,
    "engineSpeedRpm": 321.25,
    "engineCoolantTemperature": -30.0,
    "fuelEconomy": 1.911987,
    "fuelRate": 11.35,
    "gpsSource": "EITHER_DEVICE",
    "hdop": 0,
    "highResOdometerKm": 0.0,
    "ignition": 0,
    "odometerKm": 200.0,
    "ptoStatus": 1,
    "seatBelt": 0,
    "parkingBrake": 1,
    "fuelLevel": 0,
    "idlFuelConsumed": 0,
    "throttle": 102.0,
    "engineTotalHours": 37.5,
    "totalEngineHours": 37.5,
    "totalFuelUsed": 0.0,
    "transCurrentGear": 0,
    "tripOdometerKm": 100.0,
    "vehicleSpeedKph": 10.03842,
    "vin": "20UYA31581L000000",
    "driverHistoryId": 5112165,
    "latitude": 0.0,
    "longitude": 0.0,
    "numSatellites": 0,
    "state": "IL",
    "userId": 1252733,
    "accountId": 1248541,
    "id": 162171,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Create

API PATH: /api/v2/vbusData
METHOD: POST
EXAMPLE REQUEST: 
[
  {
    "assetId": 1324556,
    "timestamp": "2018-06-11T12:00:00.000Z",
    "batteryVoltage": 1.5,
    "engineOilPressure": 28.0,
    "engineSpeedRpm": 321.25,
    "engineCoolantTemperature": -30.0,
    "fuelEconomy": 1.911987,
    "fuelRate": 11.35,
    "gpsSource": "EITHER_DEVICE",
    "hdop": 0,
    "highResOdometerKm": 0.0,
    "ignition": 0,
    "odometerKm": 200.0,
    "ptoStatus": 1,
    "seatBelt": 0,
    "parkingBrake": 1,
    "throttle": 102.0,
    "engineTotalHours": 37.5,
    "totalEngineHours": 37.5,
    "fuelLevel": 0,
    "idlFuelConsumed": 0,
    "totalFuelUsed": 0.0,
    "transCurrentGear": 0,
    "tripOdometerKm": 100.0,
    "vehicleSpeedKph": 10.03842,
    "vin": "20UYA31581L000000",
    "driverHistoryId": 5112165,
    "latitude": 0.0,
    "longitude": 0.0,
    "numSatellites": 0,
    "state": "IL",
    "userId": 1252733
  }
]
EXAMPLE REQUEST: 
[
  {
    "assetId": 1324556,
    "timestamp": "2018-06-11T12:00:00.000Z",
    "batteryVoltage": 1.5,
    "engineOilPressure": 28.0,
    "engineSpeedRpm": 321.25,
    "engineCoolantTemperature": -30.0,
    "fuelEconomy": 1.911987,
    "fuelRate": 11.35,
    "gpsSource": "EITHER_DEVICE",
    "hdop": 0,
    "highResOdometerKm": 0.0,
    "ignition": 0,
    "odometerKm": 200.0,
    "ptoStatus": 1,
    "seatBelt": 0,
    "parkingBrake": 1,
    "throttle": 102.0,
    "engineTotalHours": 37.5,
    "totalEngineHours": 37.5,
    "totalFuelUsed": 0.0,
    "transCurrentGear": 0,
    "fuelLevel": 0,
    "idlFuelConsumed": 0,
    "tripOdometerKm": 100.0,
    "vehicleSpeedKph": 10.03842,
    "vin": "20UYA31581L000000",
    "driverHistoryId": 5112165,
    "latitude": 0.0,
    "longitude": 0.0,
    "numSatellites": 0,
    "state": "IL",
    "userId": 1252733,
    "accountId": 1248541,
    "id": 162171,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Update

API PATH: /api/v2/vbusData
METHOD: PUT
EXAMPLE RESPONSE: 
[
  {
    "assetId": 1324556,
    "timestamp": "2018-06-11T12:00:00.000Z",
    "batteryVoltage": 1.5,
    "engineOilPressure": 28.0,
    "engineSpeedRpm": 321.25,
    "engineCoolantTemperature": -30.0,
    "fuelEconomy": 1.911987,
    "fuelRate": 11.35,
    "gpsSource": "EITHER_DEVICE",
    "hdop": 0,
    "highResOdometerKm": 0.0,
    "ignition": 0,
    "odometerKm": 200.0,
    "ptoStatus": 1,
    "seatBelt": 0,
    "parkingBrake": 1,
    "throttle": 102.0,
    "engineTotalHours": 37.5,
    "totalEngineHours": 37.5,
    "totalFuelUsed": 0.0,
    "fuelLevel": 0,
    "idlFuelConsumed": 0,
    "transCurrentGear": 0,
    "tripOdometerKm": 100.0,
    "vehicleSpeedKph": 10.03842,
    "vin": "20UYA31581L000000",
    "driverHistoryId": 5112165,
    "latitude": 0.0,
    "longitude": 0.0,
    "numSatellites": 0,
    "state": "IL",
    "userId": 1252733,
    "id": 162171
  }
]
EXAMPLE REQUEST: 
[
  {
    "assetId": 1324556,
    "timestamp": "2018-06-11T12:00:00.000Z",
    "batteryVoltage": 1.5,
    "engineOilPressure": 28.0,
    "engineSpeedRpm": 321.25,
    "engineCoolantTemperature": -30.0,
    "fuelEconomy": 1.911987,
    "fuelRate": 11.35,
    "gpsSource": "EITHER_DEVICE",
    "hdop": 0,
    "highResOdometerKm": 0.0,
    "ignition": 0,
    "odometerKm": 200.0,
    "ptoStatus": 1,
    "seatBelt": 0,
    "parkingBrake": 1,
    "throttle": 102.0,
    "engineTotalHours": 37.5,
    "totalEngineHours": 37.5,
    "totalFuelUsed": 0.0,
    "fuelLevel": 0,
    "idlFuelConsumed": 0,
    "transCurrentGear": 0,
    "tripOdometerKm": 100.0,
    "vehicleSpeedKph": 10.03842,
    "vin": "20UYA31581L000000",
    "driverHistoryId": 5112165,
    "latitude": 0.0,
    "longitude": 0.0,
    "numSatellites": 0,
    "state": "IL",
    "userId": 1252733,
    "accountId": 1248541,
    "id": 162171,
    "lastChangedDate": "2018-06-11T12:00:00.000Z"
  }
]

Delete

API PATH: /api/v2/vbusData/<id>
METHOD: DELETE

API error calls

ERROR MESSAGE POSSIBLE CAUSES
Asset ID is required. POST and PUT methods require Asset ID field