FleetUp API Documentation

Overview

This document describes external APIs for third-party development to utilize FleetUp data.

First, get your access_token, then invoke the other APIs.  The access_token expires after one hour, so please get your new access_token before it expires.

If you have several servers invoking FleetUp APIs, please make sure your access_token is the same, repeatedly getting access_token’s will make your service unstable.

NOTE:   We will notify you if we change from HTTP to HTTPS in the future.

FleetUp will provide the following:

  • The account ID.
  • The secret key of the account.
  • The documentation of how to use the JSON (JavaScript Object Notation) Web service.
  • The JSON Web service calls for getting an authenticated session.   The JSON Web Service communicates over the HTTP (Hyper Text Transfer Protocol) to provide data in JSON format.

A Web service is a function call to a remote server to get a specific set of data.  JSON is very lightweight in overhead because it only returns text-based data in key-value pair format. The JSON data can be converted into native objects in many programming languages.

Here is how to get GPS coordinates and other data (RPM, Speed, direction, etc…):

  • Get a token, and start a timer.
  • Get a “LastSerialNo” (A) as a starting point.
  • Make sure there are vehicles running.
  • Wait for at least 30 seconds, because the vehicles will need to submit live GPS data.
  • Use this LastSerialNo ( A ) to get data (GPS, RPM, etc…) and “LastSerialNo” (B).
  • Wait for another 30 seconds, then use this “LastSerialNo” ( B ) to get the next batch of data and “LastSerialNo” ( C ).
  • Wait for another 30 seconds, then use this “LastSerialNo” ( C ) to get the next batch of data and “LastSerialNo” ( D )
  • And so on…
  • When the token expires after an hour, get another token.

API List

Get Access Token

1. Summary

ProtocolHTTP
Request MethodGET
Request URLhttp://api.fleetuptrace.com/token
Data FormatString

NOTE:  FleetUp will provide you the AcctID and App Secret Keys when an account is created.

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
secretApp SecretYes
Example

http://api.fleetuptrace.com/token?acctId=381&secret=n9s31a8ae363mdvqjnxtteh9nvx4tt0m

3.  Response data

NameDescription
tokenAccess token
expireTimeCurrentTime(In Seconds) + 3600. The token will expire in 3600 seconds, so you need to invoke this API again in 3600 seconds.
Example

Success

   {
      "expireTime": 1441037979,
      "token": "3q22tx"
   }

 
Fail

   { 
      "errorCode": "001", 
      "errorMsg": "invalid app secret" 
   }

Get Latest GPS Position

This API will return the ID of the latest GPS position.  This will allow you to retrieve the next GPS coordinates that are coming live into the database.

1.  Summary

ProtocolHTTP
Request MethodPOST
Request URLhttp://api.fleetuptrace.com/gps/getLatestPosition?token=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
secretApp SecretYes

 

Example
   {
      "acctId": "181",
      "secret": "n9s31a8ae363mdvqjnxtteh9nvx4tt0m"
   }

3.  Response Data

NameDescription
lastSerialNoThe ID of the latest GPS position in the database.

 

Example

Success

   345382005


Fail

   {
      "errorCode": "001",
      "errorMsg": "invalid acctId"
   }

Get GPS Data

1.  Summary

ProtocolHTTP
Request MethodPOST
Request URLhttp://api.fleetuptrace.com/gps/getGps?token=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
lastSerialNoThe ID of the latest GPS position in the database.Yes
Example
   {
      "acctId": "181",
      "lastSerialNo": "345382005"
   }

3.  Response Data

NameDescription
totalRecordsTotal records
lastSerialNoID of the latest GPS position, to be used for next retrieval of GPS coordinates.
gpsDataGPS data
gpsData
NameDescription
devIdDevice ID, e.g. 213GL201401235
idThe ID of this GPS position in the database.
acconTimeVehicle ignition time, UTC time zone, e.g. 20150831010101
tmTimeGPS trigger time, UTC time zone, e.g. 20150831010233
latGPS data latitude, e.g. 142198116
Conversion to Decimal Degree format:
142198116 / 3600000 = 39.4994767 (Positive # = North, Negative # = South)
If you need to convert from Decimal-Degree format into the Degree-Minutes-Seconds format, see this URL for the formulas:
http://www.rapidtables.com/convert/number/degrees-to-degrees-minutes-seconds.htm
lngGPS data longitude, e.g., -438079242
Conversion to Decimal Degree format:
-438079242 / 3600000 = -121.688678 (Positive # = East, Negative # = West)
speedThe value for instant speed, unit: cm/s, e.g. 2861
Conversion:
2861 * 0.036 km/h = 102.99 km/h
directionThe returned number is between 0 and 3600, e.g. 1311
Conversion:
1311/10 = 131.1
The direction of where the vehicle is driving toward.  There are 360 degrees, with zero at the 12 o’clock position, increasing in clock-wise direction.  For example:
0 = 12 o’clock 90 = 3 o’clock
e.g.  1311  will be 1311 / 10 = 131.1  (direction in between 4 o’clock and 5 o’clock)
rpmRPM (Revolutions Per Minute)

 

Example

Success

   {
      "totalRecords": 200,
      "lastSerialNo": 345419458,
      "gpsData": [{
         "id": 345382196,
         "direction": 0,
         "lat": 123627660,
         "lng": -426686352,
         "acconTime": 20150831142854,
         "devId": "213GL2014011583",
         "tmTime": 20150831145416,
         "speed": 77,
         "rpm": 1871
      },
      ...
      {
         "id": 345419458,
         "direction": 1311,
         "lat": 123198780,
         "lng": -426609264,
         "acconTime": 20150831142109,
         "devId": "213GL2014003084",
         "tmTime": 20150831151125,
         "speed": 453,
         "rpm": 1198
      }]
   }

Fail

   {
      "errorCode": "001",
      "errorMsg": "invalid acctId"
   }

Get Devices Last GPS Location

This API will return the last known GPS coordinates of all devices under the account.

1.  Summary

ProtocolHTTP
Request MethodPOST
Request URLhttp://api.fleetuptrace.com/gps/getDevicesLastLocation?token=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
Example
   {
      "acctId": "181"
   }

3.  Response Data

NameDescription
devIdDevice ID
tmTimeGPS trigger time, UTC time zone, e.g. 20150831010233
latLast coordinate’s latitude
Conversion to Decimal Degree format:
142198116 / 3600000 = 39.4994767 (Positive # = North, Negative # = South)
If you need to convert from Decimal-Degree format into the Degree-Minutes-Seconds format, see this URL for the formulas:
http://www.rapidtables.com/convert/number/degrees-to-degrees-minutes-seconds.htm
lngLast coordinate’s longitude
Conversion to Decimal Degree format:
-438079242 / 3600000 = -121.688678 (Positive # = East, Negative # = West)

 

Example

Success

   [
      {
         "devId":"213NX2016000030",
         "tmTime":20171221223901,
         "lat":122932530,
         "lng":-425697372
      },
      ...
      {
         "devId":"7560504447",
         "tmTime":20171222163421,
         "lat":123168713,
         "lng":-425622739
      }
   ]

Fail

   {
      "errorCode": "001",
      "errorMsg": "invalid acctId"
   }

Get Geofence Name

This API will return a list of all GeoFences belonging to an account. It requires Account ID as input parameter.

1.  Summary

ProtocolHTTP
Request MethodPOST
Request URLhttp://api.fleetuptrace.com/fencealert/getFenceNames?token=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
Example
   {
      "acctId": "20521"
   }

3. Response Data

NameDescription
fenceNamesList of fence names belonging to the account
Example

Success

   {
      "fenceNames":[{  
         "fenceName": "SGD Tofu House"
      },
      {  
         "fenceName": "Office"
      }]
   }

 
Fail

   {
      "errorCode": "001",
      "errorMsg": "invalid acctId"
   }

Get Geofence Alerts

This API will return the GeoFence Alert action type. It requires the Account ID, Device ID and Start Date and Time as an input parameter.  

1.  Summary

ProtocolHTTP
Request MethodPOST
Request URLhttp://api.fleetuptrace.com/fencealert/getGeoFenceAlert?token=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
devIdDevice IDYes
startDateStart Date and Time (UTC-0)Yes
Example
   {
      "acctId": "20521",
      "devId": "213GL2014000070",
      "startDate": "20160331000000"
   }

3.  Response Data

NameDescription
AlertsSet of all geo fence alerts in that day
AlertAction

1 : Entering Fence

2 : Exiting Fence

NOTE: If no alerts were generated within the time period entered, the request will return an empty JSON object.

Example

Success

   {   
      "alerts":[{
        "devId": "213GL2014000070",
        "acconTime": 20160331203738,
        "fenceId": 524,
        "startGpsId": 721177737,
        "alertAction": 2,
        "fenceName": "Polygon Test"
        }
        {
        "devId": "213GL2014000070",
        "acconTime": 20160331207848,
        "fenceId": 454,
        "startGpsId": 721177453,
        "alertAction": 1,
        "fenceName": "Circle Test"
      }]
   }

 
Fail

   {
      "errorCode": "001",
      "errorMsg": "invalid acctId"
   }

Get Device List

1.  Summary

ProtocolHTTP
Request MethodPOST
Request URLhttp://api.fleetuptrace.com/device/list?token=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
Example
   {
      "acctId": "181"
   }

3.  Response Data

NameDescription
devices

Device list

This returns all the device names within this account with their license numbers and vehicle names.

device
NameDescription
devIdDevice ID, e.g. 213GL201401235
licenseLicense number, e.g.  HYFT36 (TBD)
vehicleNameVehicle Name in FleetUP
status

0 : offline

1 : online

Example

Success

  {
    "devices":[{
        "status":"0",
        "vehicleName":"2010-Peterbilt-387",
        "license":"480",
        "devId":"213NX2016000030"
    },{
        "status":"1",
        "vehicleName":"2016-Freightliner-Cascadia",
        "license":"510",
        "devId":"213NX2016000968"
    }]
  }

 
Fail

   {
      "errorCode": "001",
      "errorMsg": "invalid acctId"
   }

Get Device Status

1.  Summary

ProtocolHTTP
Request MethodPOST
Request URLhttp://api.fleetuptrace.com/device/status?token=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
devIdsDevice id list, Comma separated StringYes
Example
   {
      "acctId": "181",
      "devIds": "212GL1134601658,213TL2015001873"
   }

3.  Response Data

NameDescription
devices

Device status list

This returns all the device status(on line/off line).

device
NameDescription
devIdDevice ID, e.g. 213GL201401235
status

0 : offline

1 : online

Example

Success

   {
      "devices": [{
         "devId": "212GL1134601658",
         "status": "0"
      },
      ...
      {
         "devId": "213TL2015001873",
         "status": "1"
      }]
   }

 
Fail

   {
      "errorCode": "001",
      "errorMsg": "invalid acctId"
   }

Get Device Odometer

This API will return the device’s current odometer. It requires the Account ID and Device IDs as input parameters.  

1.  Summary

ProtocolHTTP
Request MethodPOST
Request URLhttp://api.fleetuptrace.com/device/getDeviceOdometer?token=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
devIdsDevice IDYes
Example
   {
      "acctId": "181",
      "devIds": "212GL1134601658,213TL2015001873"
   }

3.  Response Data

NameDescription
devicesDevice Object
devIdDevice ID, e.g. 213GL201401235
unitOdometer Unit, e.g. KM or miles
totalOdometerDevice total Odometer
Example

Success

   {
      "devices": [{
         "devId": "212GL1134601658",
         "unit": "miles",
         "totalOdometer": "0"
       },
       {
         "devId": "213TL2015001873",
         "unit": "miles",
         "totalOdometer": "1"
       }]
   }

 
Fail

   {
      "errorCode": "001",
      "errorMsg": "invalid acctId"
   }

Get Device Fuel Level

This API will return the device’s current Fuel Level. It requires the Account ID and Device IDs as an input parameter.  

1.  Summary

ProtocolHTTP
Request MethodPOST
Request URLhttp://api.fleetuptrace.com/device/fuelLevel?token=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
devIdsDevice IDYes
Example
   {
      "acctId": "181",
      "devIds": "212GL1134601658,213TL2015001873"
   }

3.  Response Data

NameDescription
devicesDevice Object
 devIdDevice ID, e.g. 213GL201401235
fuelLevelDevice Fuel Level
fuelLevel2Device Fuel Level
Example

Success

   {
      "devices": [{
         "devId": "212GL1134601658",
         "fuelLevel": "0",
         "fuelLevel2": "0"
      },
      ...
      {
         "devId": "213TL2015001873",
         "fuelLevel": "1",
         "fuelLevel2": "0"
      }]
    }

 
Fail

   {
      "errorCode": "001",
      "errorMsg": "invalid acctId"
   }

Get Driver List

1.  Summary

ProtocolHTTP
Request MethodGET
Request URLhttp://api.fleetuptrace.com/driver/list?token=******&acctId=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
tokenAccess tokenYes
acctIdAccount IDYes
Example

http://api.fleetuptrace.com/driver/list?token=jt7wzs&acctId=381

3.  Response Data

NameDescription
drivers

Driver list

This returns all the drivers within this account along with the vehicle they are currently operating.

driver
NameDescription
vehicleNameVehicle being operated
driverIdDriver username in FleetUp
onlineStatus

0 : driver offline

1 : driver online

driverNameDriver name in FleetUp
deviceIDDevice ID, e.g. 213GL201401235
Example

Success

   {
      "drivers":[{
         "vehicleName":"N/A",
         "driverId":"ahayes",
         "onlineStatus":"0",
         "driverName":"Angela",
         "deviceId":"N/A"
      },
      {
         "vehicleName":"FF23",
         "driverId":"Art",
         "onlineStatus":"1",
         "driverName":"Arthur Kim",
         "deviceId":"212GL1134601658"
      }]
   }

 
Fail

   {
      "errorCode": "001",
      "errorMsg": "invalid acctId"
   }

Get Driver's Overview

This API returns the Driver’s overall details along with the current status. The API requires Account ID and Driver ID as input parameter.

1.  Summary

ProtocolHTTP
Request MethodPOST
Request URLhttp://api.fleetuptrace.com/device/driveroverview?token=******
Data FormatJSON

2.  Request Data

NameDescriptionMandatory
acctIdAccount IDYes
driverIdDriver’s user ID.Yes
Example
   {
      "acctId": "10801",
      "driverId":"bcuser"
   }

3.  Response Data

NameDescription
breakRequiredMinute, Break Needed
status

User current status.

1: Off Duty

2: Sleeper

3: Driving

4: On Duty (Not Driving)

shiftLimitMinute, – Shift Hour Left
driverIddriverId
driverPhoneDriver’s phone number
cycleLimitMinute, Cycle Hour Left
violationNumViolation count. Number of violations.
shortDateDate with format of yyyyMMdd. (ex) “20150909”.
driverNameDriver Name
drivingLimitMinute, Driving Hour Left
violationSee below
violation
NameDescription
idID of HOS_VIOLATION_RECORD table
userIdUserid
type

1:Rule A

2:Rule B

3:Rule C

4:Rule D

shortDateDate with format of yyyyMMdd. (ex) “20150909”.
startTime

Violation start time. Unit is minute.

(ex) 60 : an hour. 90: an hour and half.

endTime

Violation end time. Unit is minute.

(ex) 60 : an hour. 90: an hour and half.  

flag0:original triggered; 1: Auto generate
Example

Success

   [{
      "breakRequired": 219, // 3 Hours and 39 Minutes! - Break Needed
      "status": 1,
      "shiftLimit": 529, // 8 Hours and 49 Minutes! - Shift Hour Left
      "violation": [],
      "vehicle": "N/A",
      "driverId": "ALLIANCE",
      "driverPhone": "6654396344",
      "cycleLimit": 3400, // 56 Hours and 40 Minutes! - Cycle Hour Left
      "violationNum": 0,
      "shortDate": 20160608,
      "driverName": "ALLIANCE",
      "drivingLimit": 400 // 6 Hours and 40 Minutes! - Driving Hour Left
   }]
   [{
      "breakRequired": -222, // - Break Needed
      "status": 1,
      "shiftLimit": 138, // Shift Hour Left
      "violation": [{
         "id": 21864300,
         "userId": "bcuser",
         "type": 1,
         "shortDate": 20160608,
         "startTime": 480,
         "endTime": 702,
         "flag": 0
      },
      {
         "id": 21865301,
         "userId": "bcuser",
         "type": 3,
         "shortDate": 20160608,
         "startTime": 660,
         "endTime": 702,
         "flag": 0
      }],
      "vehicle": "N/A",
      "driverId": "bcuser",
      "driverPhone": "",
      "cycleLimit": 2898, // Cycle Hour Left
      "violationNum": 2,
      "shortDate": 20160608,
      "driverName": "BC User",
      "drivingLimit": -42   // Driving Hour Left
   }]

 
Fail

   {
      "errorCode": "001", 
      "errorMsg": "invalid acctId"
   }
   {
      "errorCode": "005",
      "errorMsg":"Driver[BCUSER] does not belong to the account[781]"
   }
Suggest Edit