Update Trip Status

Trip Management’s update trip status API handles accept, reject, cancel, complete, and receive trip messages by saving the status to the database. After the update is successfully processed, it notifies the user of the trip status update. After a trip is accepted, the route path for the trip will be saved into the database.

POST /trip/tripStatus #

(Note: Replaces /trip/reply, which has been deprecated.)

Resource URL #

https://tripmanagement.alk.com/api/trip/tripStatus

Request Fields #

Field Description Type Required
tripId The alkTripId returned when you planned the trip.
Note: If no trip is found with the given alkTripId, then an error message will be returned. If the tmsTripId in your planning system is also supplied in the body of this request, then the alkTripId will be ignored irrespective of whether it is valid or not and the trip corresponding to the provided tmsTripId will be updated. In this case, if no trip is found with the given tmsTripId, then an error message will be returned. 
integer
Yes if tmsTripId is not supplied.
tmsTripId The tmsTripId of your previously generated route.
Note: Even if tripId, which is the alkTripId, is also supplied with this request, it will be ignored and only trip corresponding to the given tmsTripId will be updated. If no trip is found with the given tmsTripId, then an error message will be returned. 
string
Yes if tripId is not supplied.
status The status of the route.
  • 0 = Rejected
  • 1 = Accepted
  • 2 = Completed
  • 3 = Canceled
  • 4 = Received
 
integer
Yes
timeStamp Timestamp when the trip message was sent from CoPilot. The value must be in ISO-8601 format. 
date
Yes
loc GPS Coordinates tracked by the vehicle. 
GPSCoords
Yes
loc > coords The object containing the latitude/longitude of the GPS. 
Coords object
Yes
loc > coords > lat The GPS latitude. Minimum 4 decimal digits required. Desired 6 decimal digits. 
string
Yes
loc > coords > lon The GPS longitude. Minimum 4 decimal digits required. Desired 6 decimal digits. 
string
Yes
loc > Speed Speed 
integer
No
loc > Heading Heading 
integer
No
loc > Altitude Altitude 
integer
No
loc > DeviceDT The device time. The value must be in ISO-8601 format. 
string
No

Response Fields #

Field Description Type
success true or false 
boolean
errorCode Numeric error code. If success is true, errorCode can be ignored.
errorCode = -1, trip can’t be found.
errorCode = -3, trip last modification happened after the timestamp of this request. 
integer

Example #

Sample Request # 

{
  "tripId": 12345,
  "status": 2,
  "timeStamp": "2018-03-20T15:00:42.624Z",
  "loc": {
    "Coords": {
      "Lat": "42.364551",
      "Lon": "-71.180604"
    }
  }
}

Sample Response # 

{
  "success": true,
  "errorCode": 0
}

Error Conditions #

Field Description Type Values
ErrorType The type of error that occurred. 
string
ArgumentException - a required field was not supplied or an invalid value was passed or an inappropriate action was attempted. Correct the error and try again.
Description An error message describing what occurred. 
string
This message will describe how to fix the error or what went wrong.
ErrorCode A numerical error code (if applicable). 
integer

ArgumentException Examples # 

{
  "ErrorType": "ArgumentException",
  "Description": "Can't update trip status with timestamp older than trip last modified time",
  "ErrorCode": null
}

{
  "ErrorType": "ArgumentException",
  "Description": "Can't perform modification action 'Accepted' if a trip has been 'Canceled'.",
  "ErrorCode": null
}

{
  "ErrorType": "ArgumentException",
  "Description": "Can't perform modification action 'Canceled' if a trip has been 'Completed'.",
  "ErrorCode": null
}
Last updated March 19, 2020.