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

Protocol HTTP
Request Method GET
Request URL http://api.fleetuptrace.com/token
Data Format String

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

2.  Request Data

Name Description Mandatory
acctId Account ID Yes
secret App Secret Yes
Example

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

3.  Response data

Name Description
token Access token
expireTime CurrentTime(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

Protocol HTTP
Request Method POST
Request URL http://api.fleetuptrace.com/gps/getLatestPosition?token=******
Data Format JSON

2.  Request Data

Name Description Mandatory
acctId Account ID Yes
secret App Secret Yes

 

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

3.  Response Data

Name Description
lastSerialNo The ID of the latest GPS position in the database.

 

Example

Success

 345382005


Fail

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

Get GPS Data

1.  Summary

Protocol HTTP
Request Method POST
Request URL http://api.fleetuptrace.com/gps/getGps?token=******
Data Format JSON

2.  Request Data

Name Description Mandatory
acctId Account ID Yes
lastSerialNo The ID of the latest GPS position in the database. Yes
Example
 { "acctId": "181", "lastSerialNo": "345382005" }

3.  Response Data

Name Description
totalRecords Total records
lastSerialNo ID of the latest GPS position, to be used for next retrieval of GPS coordinates.
gpsData GPS data
gpsData
Name Description
devId Device ID, e.g. 213GL201401235
id The ID of this GPS position in the database.
acconTime Vehicle ignition time, UTC time zone, e.g. 20150831010101
tmTime GPS trigger time, UTC time zone, e.g. 20150831010233
lat GPS 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
lng GPS data longitude, e.g., -438079242
Conversion to Decimal Degree format:
-438079242 / 3600000 = -121.688678 (Positive # = East, Negative # = West)
speed The value for instant speed, unit: cm/s, e.g. 2861
Conversion:
2861 * 0.036 km/h = 102.99 km/h
direction The 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)
rpm RPM (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 Geofence Name

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

1.  Summary

Protocol HTTP
Request Method POST
Request URL http://api.fleetuptrace.com/fencealert/getFenceNames?token=******
Data Format JSON

2.  Request Data

Name Description Mandatory
acctId Account ID Yes
Example
 { "acctId": "20521" }

3. Response Data

Name Description
fenceNames List 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

Protocol HTTP
Request Method POST
Request URL http://api.fleetuptrace.com/fencealert/getGeoFenceAlert?token=******
Data Format JSON

2.  Request Data

Name Description Mandatory
acctId Account ID Yes
devId Device ID Yes
startDate Start Date and Time (UTC-0) Yes
Example
 { "acctId": "20521", "devId": "213GL2014000070", "startDate": "20160331000000" }

3.  Response Data

Name Description
Alerts Set 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

Protocol HTTP
Request Method POST
Request URL http://api.fleetuptrace.com/device/list?token=******
Data Format JSON

2.  Request Data

Name Description Mandatory
acctId Account ID Yes
Example
 {     "acctId": "181" }

3.  Response Data

Name Description
devices

Device list

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

device
Name Description
devId Device ID, e.g. 213GL201401235
license License number, e.g.  HYFT36 (TBD)
vehicleName Vehicle 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

Protocol HTTP
Request Method POST
Request URL http://api.fleetuptrace.com/device/status?token=******
Data Format JSON

2.  Request Data

Name Description Mandatory
acctId Account ID Yes
devIds Device id list, Comma separated String Yes
Example
 { "acctId": "181", "devIds": "212GL1134601658,213TL2015001873" }

3.  Response Data

Name Description
devices

Device status list

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

device
Name Description
devId Device 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

Protocol HTTP
Request Method POST
Request URL http://api.fleetuptrace.com/device/getDeviceOdometer?token=******
Data Format JSON

2.  Request Data

Name Description Mandatory
acctId Account ID Yes
devIds Device ID Yes
Example
 { "acctId": "181", "devIds": "212GL1134601658,213TL2015001873" }

3.  Response Data

Name Description
devices Device Object
devId Device ID, e.g. 213GL201401235
unit Odometer Unit, e.g. KM or miles
totalOdometer Device 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

Protocol HTTP
Request Method POST
Request URL http://api.fleetuptrace.com/device/fuelLevel?token=******
Data Format JSON

2.  Request Data

Name Description Mandatory
acctId Account ID Yes
devIds Device ID Yes
Example
 { "acctId": "181", "devIds": "212GL1134601658,213TL2015001873" }

3.  Response Data

Name Description
devices Device Object
 devId Device ID, e.g. 213GL201401235
fuelLevel Device Fuel Level
fuelLevel2 Device 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

Protocol HTTP
Request Method GET
Request URL http://api.fleetuptrace.com/driver/list?token=******&acctId=******
Data Format JSON

2.  Request Data

Name Description Mandatory
token Access token Yes
acctId Account ID Yes
Example

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

3.  Response Data

Name Description
drivers

Driver list

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

driver
Name Description
vehicleName Vehicle being operated
driverId Driver username in FleetUp
onlineStatus

0 : driver offline

1 : driver online

driverName Driver name in FleetUp
deviceID Device 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

Protocol HTTP
Request Method POST
Request URL http://api.fleetuptrace.com/device/driveroverview?token=******
Data Format JSON

2.  Request Data

Name Description Mandatory
acctId Account ID Yes
driverId Driver’s user ID. Yes
Example
 { "acctId": "10801", "driverId":"bcuser" }

3.  Response Data

Name Description
breakRequired Minute, Break Needed
status

User current status.

1: Off Duty

2: Sleeper

3: Driving

4: On Duty (Not Driving)

shiftLimit Minute, – Shift Hour Left
driverId driverId
driverPhone Driver’s phone number
cycleLimit Minute, Cycle Hour Left
violationNum Violation count. Number of violations.
shortDate Date with format of yyyyMMdd. (ex) “20150909”.
driverName Driver Name
drivingLimit Minute, Driving Hour Left
violation See below
violation
Name Description
id ID of HOS_VIOLATION_RECORD table
userId Userid
type

1:Rule A

2:Rule B

3:Rule C

4:Rule D

shortDate Date 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.  

flag 0: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