Update Trip Status
Once a trip is created, the default tripStatus is set to Planned and this will be displayed accordingly in the Plan Trip API response. tripStatus is then monitored until the trip is completed.
The Update Trip Status API is used to change the status of a trip to one of five values:
Rejected- The driver rejected this trip and the trip is not in an active state.Accepted- The driver accepted this trip and the trip is now active. This sets thetripStatustoInProgress.Completed- All open stops on the trip are completed. This sets thetripStatustoCompleted. Once a trip is completed, it cannot be reopened or cancelled.Cancelled- This sets thetripStatustoCancelled. Once a trip is cancelled, it cannot be reopened or completed.Received- This status can be used to confirm that a trip was delivered to a device and a driver received it. It does not put the tripInProgress, which requires the additional step ofAccepted.
POST /trip/tripStatus
Resource URL
https://tripmanagement.trimblemaps.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.
|
integer | Yes |
timeStamp
| Timestamp when the trip status update was sent. 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
}