Update trip by ID
/fleetMonitoring/clientapi/v2/trips/{tripId}
Permissions
IoTFleetMonitoringAdministrator - A user who is a part of IoTFleetMonitoringAdministratorsGroup can update tripStatus for all the trips. The user can update trip name, route, planned arrival and departure times, latest and earliest start time, planned driver distance and planned driver duration in seconds, vehicle and driver associated with a NOT_STARTED trip.
IoTFleetMonitoringDriver - A user who is a part of IoTFleetMonitoringDriversGroup can update the trip assigned to them.The user can update vehicle and tripStatus for NOT_STARTED trip and can update only the tripStatus for an IN_PROGRESS trip.
Request
- application/json
-
tripId: string
Trip ID to be patched.
-
X-HTTP-Method-Override: string
To perform a partial update of the trip, POST request should be orchestrated with method override set to PATCH.
-
X-ORACLE-IOT-ORG(optional): string
To allow targeting requests to different organizations. The header value should contain the organization identifier(orgId). This header is optional, if not provided orgId will be ORA_DEFAULT_ORG
object
-
destination(optional):
object TripStopRecord_update
-
driver(optional):
object TripDriverInfoModel_update
-
earliestStartTime(optional):
integer
Trip planned earliest start time (epoch time in milliseconds)
-
latestStartTime(optional):
integer
Trip planned latest start time (epoch time in milliseconds)
-
name(optional):
string
Trip name
-
plannedDriveDistance(optional):
integer
Total planned length of the trip
-
plannedDriveDurationSeconds(optional):
integer
Total planned drive duration of the trip in seconds
-
source(optional):
object TripStopRecord_update
-
tripStatus:
string
One of [NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELLED].
-
vehicle(optional):
object TripVehicleInfoModel_update
object
-
address(optional):
string
Unified full address, e.g. 500 Oracle Parkway::Redwood City::CA::US::94065 . Must be provided if geoLocation is not specified.
-
city(optional):
string
Name of City
-
country(optional):
string
Name of country
-
distanceToNextStop(optional):
number
Estimated distance to next stop
-
geoLocation(optional):
object GeoPosition_update
-
plannedArrivalTime(optional):
integer
Planned Trip arrival time (in millisecond)
-
plannedDepartureTime(optional):
integer
Planned Trip departure time (in millisecond)
-
postalCode(optional):
string
Postal/Zip code
-
state(optional):
string
Name of State
-
street(optional):
string
Name of Street
-
timeZone(optional):
string
Time zone of the time fields
object
-
externalId(optional):
string
External Id of the driver associated with this trip
-
loginId(optional):
string
Login Id of the driver associated with this trip
-
name(optional):
string
Name of the driver associated with this trip
object
-
name(optional):
string
Name of the vehicle assigned to the trip
object
-
additionalElements(optional):
array additionalElements
Property description was not set
-
altitude(optional):
number
Property description was not set
-
latitude(optional):
number
Property description was not set
-
longitude(optional):
number
Property description was not set
-
valid(optional):
boolean
Property description was not set
Response
- application/json
- application/vnd.oracle.resource+json;type=singular
200 Response
object
-
destination:
object TripStopRecord_receive
-
driver:
object TripDriverInfoModel_receive
-
driverId:
string
ID of the driver associated with the trip
-
earliestStartTime:
integer
Trip planned earliest start time (epoch time in milliseconds)
-
endTime:
integer
Trip end time (epoch time in milliseconds)
-
expectedDuration:
integer
Expected duration of the Trip (seconds) : Taken from Trip planning info; if not provided then retrieved from MapServiceProvider, else set as 0
-
id:
string
Trip ID
-
lastModifiedTime:
integer
Last modified time (epoch time in milliseconds)
-
latestStartTime:
integer
Trip planned latest start time (epoch time in milliseconds)
-
name:
string
Trip name
-
plannedDriveDistance:
integer
Total planned length of the trip
-
plannedDriveDurationSeconds:
integer
Total planned drive duration of the trip in seconds
-
source:
object TripStopRecord_receive
-
startTime:
integer
Trip start time (epoch time in milliseconds)
-
stops:
array stops
List of stops for the trip
-
stopsClassification:
string
One of [SINGLE_STOP, DUAL_STOP, TRIPLE_STOP, MULTI_STOP, NON_STOP].
-
stopsCompleted:
integer
Number of stops completed for the trip
-
totalStops:
integer
Total stops for the trip
-
tripContext:
array tripContext
List of Trip Context for the trip
-
tripLength:
number
Total length of the Trip
-
tripLengthClassification:
string
One of [SHORT, MEDIUM, LONG].
-
tripStatus:
string
One of [NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELLED].
-
tripTemplateId:
string
ID of the tripTemplate associated with the trip
-
tripType:
string
Trip type either Planned or Automatic trip
-
vehicle:
object TripVehicleInfoModel_receive
-
vehicleId:
string
ID of the vehicle associated with this trip
object
-
address:
string
Unified full address, e.g. 500 Oracle Parkway::Redwood City::CA::US::94065 . Must be provided if geoLocation is not specified.
-
arrivalTime:
integer
Trip arrival time (millisecond)
-
city:
string
Name of City
-
country:
string
Name of country
-
departureTime:
integer
Trip departure time (millisecond)
-
distanceToNextStop:
number
Estimated distance to next stop
-
estimatedArrivalTime:
integer
Estimated arrival time (millisecond)
-
estimatedDepartureTime:
integer
Estimated departure time (millisecond)
-
estimatedTimeToNextStop:
integer
Estimated time it will take to reach next stop (second)
-
expectedDurationFromStart:
integer
Expected duration from Start to arrive at this Stop (seconds)
-
geoLocation:
object GeoPosition_receive
-
plannedArrivalTime:
integer
Planned Trip arrival time (in millisecond)
-
plannedDepartureTime:
integer
Planned Trip departure time (in millisecond)
-
postalCode:
string
Postal/Zip code
-
state:
string
Name of State
-
stopDurationInSeconds:
integer
Stop duration in seconds
-
stopSequence:
integer
Sequence number of the stop
-
stopType:
string
The reason for stopping
-
street:
string
Name of Street
-
timeZone:
string
Time zone of the time fields
object
-
externalId:
string
External Id of the driver associated with this trip
-
loginId:
string
Login Id of the driver associated with this trip
-
name:
string
Name of the driver associated with this trip
object
-
name:
string
Name of the vehicle assigned to the trip
-
registrationNumber:
string
Registration number of the vehicle assigned to the trip
-
type:
string
Type of the vehicle assigned to the trip
object
-
additionalElements:
array additionalElements
Property description was not set
-
altitude:
number
Property description was not set
-
latitude:
number
Property description was not set
-
longitude:
number
Property description was not set
-
valid:
boolean
Property description was not set
object
-
externalId:
string
The ID of the shipment in the external system, in case of connected systems
-
name:
string
Trip Context name
-
type:
string
Trip Context type either Shipment or default trip
-
value:
string
Trip Context Id, either Trip or Shipment Id
400 Response
401 Response
404 Response
405 Response
406 Response
415 Response
Examples
curl -X POST
-u <username>:<password>
-H 'Accept: application/json'
-H 'Content-Type: application/json'
--header "X-HTTP-Method-Override: PATCH"
https://iotserver/fleetMonitoring/clientapi/v2/trips/{tripId}
Example of Request Body
The following example shows the content of the request body in JSON format:
Update a NOT_STARTED trip with IoTFleetMonitoringAdministrator user
The following example shows the content of the request body in JSON format to update a trip using IoTFleetMonitoringAdministrator role credentials:
{
"vehicle": {
"name": "Vehicle_Name"
},
"driver": {
"name": "Driver_Name",
"loginId": "Driver_Login_ID"
},
"tripStatus": "NOT_STARTED",
"earliestStartTime": 1528957500000,
"latestStartTime": 1528959500000,
"plannedDriveDistance": 560,
"plannedDriveDurationSeconds": 72000
}
Update route of a NOT_STARTED trip with IoTFleetMonitoringAdministrator user
NOTE
Provide the complete trip route to update a trip
The following example shows the content of the request body in JSON format to update a trip using IoTFleetMonitoringAdministrator role credentials:
{
"source": {
"street": "500 Oracle Parkway",
"city": "Redwood City",
"state": "CA",
"country": "US",
"postalCode": "94065",
"plannedArrivalTime": "1535697309805",
"plannedDepartureTime": "1535697309805"
},
"destination": {
"street": "4210 Network Circle",
"city": "Santa Clara",
"state": "CA",
"country": "US",
"postalCode": "95054",
"expectedDurationFromStart": 172800,
"plannedArrivalTime": "1535697309805"
},
"stops": [{
"street": "475 Sansome Street",
"city": "San Francisco",
"state": "CA",
"country": "US",
"postalCode": "94111",
"expectedDurationFromStart": 43200,
"plannedArrivalTime": "1535697309805",
"plannedDepartureTime": "1535697309805"
}]
}
Update a NOT_STARTED trip with IoTFleetMonitoringDriversGroup user credentials of the driver assigned to the trip
The following example shows the content of the request body in JSON format to update a trip using role credentials of IoTFleetMonitoringDriver assigned to the trip:
{
"vehicle": {
"name": "Vehicle_Name"
},
"tripStatus" : "IN_PROGRESS"
}
Update an IN_PROGRESS trip
The following example shows the content of the request body in JSON format to update an IN_PROGRESS trip:
{
"tripStatus":"COMPLETED"
}
Example of Response Body
The following example shows the content of the response body in JSON format:
{
"id": "D9B17614-5112-41B4-AA02-981C8F6C49F8",
"name": "HQ-SFO-SCA-Vehicle_Name",
"driverId": "7BE01256-8567-44BF-8DA3-8AEE26F33F35",
"vehicleId": "09DE39F0-A091-46B7-B0E9-3C21CC56EFE5",
"source": {
"address": "500 Oracle Parkway::Redwood City::CA::US::94065",
"geoLocation": [
-122.26223,
37.53084
],
"estimatedTimeToNextStop": 1945,
"distanceToNextStop": 38.619998931884766,
"expectedDurationFromStart": 0,
"city": "Redwood City",
"country": "US",
"plannedArrivalTime": 1519810576752,
"plannedDepartureTime": 1519810576752,
"postalCode": "94065",
"state": "CA",
"stopDurationInSeconds": 0,
"street": "500 Oracle Parkway",
"stopSequence": 0
},
"destination": {
"address": "4210 Network Circle::Santa Clara::CA::US::95054",
"geoLocation": [
-121.95267,
37.39124
],
"estimatedTimeToNextStop": 0,
"distanceToNextStop": 0,
"expectedDurationFromStart": 172800,
"city": "Santa Clara",
"country": "US",
"plannedArrivalTime": 1519983376752,
"plannedDepartureTime": 1519983376752,
"postalCode": "95054",
"state": "CA",
"stopDurationInSeconds": 0,
"street": "4210 Network Circle",
"stopSequence": 1
},
"stops": [
{
"address": "475 Sansome Street::San Francisco::CA::US::94111",
"geoLocation": [
-122.40143,
37.79461
],
"estimatedTimeToNextStop": 3100,
"distanceToNextStop": 72.06999969482422,
"expectedDurationFromStart": 43200,
"city": "San Francisco",
"country": "US",
"plannedArrivalTime": 1519853776752,
"plannedDepartureTime": 1519853776752,
"postalCode": "94111",
"state": "CA",
"stopDurationInSeconds": 0,
"street": "475 Sansome Street",
"stopSequence": 2
}
],
"tripStatus": "COMPLETED",
"earliestStartTime": 1528957500000,
"latestStartTime": 1528959500000,
"plannedDriveDistance": 560,
"plannedDriveDurationSeconds": 72000,
"expectedDuration": 5046,
"startTime": 1519810577014,
"endTime": 1519818158076,
"tripLength": 110,
"lastModifiedTime": 1519818158388,
"stopsCompleted": 0,
"totalStops": 1,
"stopsClassification": "SINGLE_STOP",
"tripLengthClassification": "MEDIUM",
"tripContext": [
{
"value": "D9B17614-5112-41B4-AA02-981C8F6C49F8",
"name": "HQ-SFO-SCA-Vehicle_Name",
"type": "TRIP"
}
],
"links": [
{
"href": "https://iotserver:443/fleetMonitoring/clientapi/v2/trips/D9B17614-5112-41B4-AA02-981C8F6C49F8/",
"rel": "self"
},
{
"href": "https://iotserver:443/fleetMonitoring/clientapi/v2/trips/D9B17614-5112-41B4-AA02-981C8F6C49F8/",
"rel": "canonical"
},
{
"href": "https://iotserver:443/fleetMonitoring/clientapi/v2/vehicles/09DE39F0-A091-46B7-B0E9-3C21CC56EFE5",
"rel": "vehicle"
},
{
"href": "https://iotserver:443/fleetMonitoring/clientapi/v2/drivers/7BE01256-8567-44BF-8DA3-8AEE26F33F35",
"rel": "driver"
}
]
}
Complete cURL Example
The following example shows a complete cURL command that you can use to perform the described operation:
curl -X POST
-u <username>:<password>
-H 'Accept: application/json'
-H 'Content-Type: application/json'
--header "X-HTTP-Method-Override: PATCH"
-d '{"latestStartTime":1469184297746,"earliestStartTime":1469184297746,"driver":{"loginId":"d676cc36-5428","name":"Name of the driver associated with this trip","externalId":"5e5f79936fd3-62c3"},"name":"Trip name","destination":{"country":"Name of country","distanceToNextStop":0.0,"address":"Unified full address, e.g. 500 Oracle Parkway::Redwood City::CA::US::94065 . Must be provided if geoLocation is not specified.","city":"Name of City","geoLocation":{"valid":false,"altitude":0.0,"latitude":0.0,"longitude":0.0,"additionalElements":["additionalElements_1","additionalElements_2","additionalElements_3"]},"street":"Name of Street","plannedArrivalTime":1469184297746,"postalCode":"Postal/Zip code","plannedDepartureTime":1469184297746,"timeZone":"Time zone of the time fields","state":"Name of State"},"source":{"country":"Name of country","distanceToNextStop":0.0,"address":"Unified full address, e.g. 500 Oracle Parkway::Redwood City::CA::US::94065 . Must be provided if geoLocation is not specified.","city":"Name of City","geoLocation":{"valid":false,"altitude":0.0,"latitude":0.0,"longitude":0.0,"additionalElements":["additionalElements_1","additionalElements_2","additionalElements_3"]},"street":"Name of Street","plannedArrivalTime":1469184297746,"postalCode":"Postal/Zip code","plannedDepartureTime":1469184297746,"timeZone":"Time zone of the time fields","state":"Name of State"},"plannedDriveDistance":12345,"plannedDriveDurationSeconds":12345,"vehicle":{"name":"Name of the vehicle assigned to the trip"},"tripStatus":"One of [NOT_STARTED, IN_PROGRESS, COMPLETED, CANCELLED]."}'
https://iotserver/fleetMonitoring/clientapi/v2/trips/{tripId}
Note that in the request,
https://iotserver
will be replaced by the name and port of your assigned IoT Cloud Service instance. The format of the Cloud Service instance is
https://myinstance-myidentitydomain.iot.us.oraclecloud.com
and the default port is 443.