Create trip
/fleetMonitoring/clientapi/v2/trips
Permissions
IoTFleetMonitoringAdministrator - A user who is a part of IoTFleetMonitoringAdministratorsGroup can create a trip with status NOT_STARTED or IN_PROGRESS.
IoTFleetMonitoringDriver - A trip created by a user who is a part of IoTFleetMonitoringDriversGroup will have the default status as IN_PROGRESS.
Request
- application/json
- application/vnd.oracle.resource+json;type=singular
-
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_create
-
driver(optional):
object TripDriverInfoModel_create
-
earliestStartTime(optional):
integer
Trip planned earliest start time (epoch time in milliseconds)
-
expectedDuration(optional):
integer
Expected duration of the Trip (seconds) : Taken from Trip planning info; if not provided then retrieved from MapServiceProvider, else set as 0
-
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_create
-
stops(optional):
array stops
List of stops for the trip
-
tripTemplateId(optional):
string
ID of the tripTemplate associated with the trip
-
vehicle(optional):
object TripVehicleInfoModel_create
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
-
expectedDurationFromStart(optional):
integer
Expected duration from Start to arrive at this Stop (seconds)
-
geoLocation(optional):
object GeoPosition_create
-
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
-
stopDurationInSeconds(optional):
integer
Stop duration in seconds
-
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:
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
Response
- application/json
- application/vnd.oracle.resource+json;type=singular
202 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
403 Response
406 Response
415 Response
Examples
curl -X POST
-u <username>:<password>
-H 'Accept: application/json'
-H 'Content-Type: application/json'
https://iotserver/fleetMonitoring/clientapi/v2/trips
Example of Request Body
The following example shows the content of the request body in JSON format:
Creating a NOT_STARTED trip with IoTFleetMonitoringAdministratorsGroup
The following example shows the content of the request body in JSON format to create a NOT_STARTED trip:
IoTFleetMonitoringAdministrator role privilege is required to create a NOT_STARTED Trip
{
"vehicle": {
"name": "Vehicle_Name"
},
"source": {
"address": "500 Oracle Parkway::Redwood City::CA::US::94065"
},
"destination": {
"address": "4210 Network Circle::Santa Clara::CA::US::95054",
"expectedDurationFromStart": 24856
},
"driver": {
"loginId": "driver4"
},
"tripStatus": "NOT_STARTED"
}
Creating a trip using trip template with IoTFleetMonitoringDriver credentials in request
The following example shows the content of the request body in JSON format to create a trip using trip template
{
"tripTemplateId": "1A7FF827-5481-4188-8BC3-F1E96A5CC9ED",
"vehicle": {
"name": "Vehicle_Name"
}
"tripStatus": "IN_PROGRESS"
}
Creating a custom trip using addresses with IoTFleetMonitoringDriversGroup credentials in request
The following example shows the content of the request body in JSON format to create a custom trip using addresses:
{
"name": "HQ-SFO-SCA-Vehicle_Name",
"source": {
"street": "500 Oracle Parkway",
"city": "Redwood City",
"state": "CA",
"country": "US",
"postalCode": "94065"
},
"destination": {
"street": "4210 Network Circle",
"city": "Santa Clara",
"state": "CA",
"country": "US",
"postalCode": "95054",
"expectedDurationFromStart": 172800
},
"stops": [
{
"street": "475 Sansome Street",
"city": "San Francisco",
"state": "CA",
"country": "US",
"postalCode": "94111",
"expectedDurationFromStart": 43200
}
],
"vehicle": {
"name": "Vehicle_Name"
},
"earliestStartTime": 1528957500000,
"latestStartTime": 1528959500000,
"plannedDriveDistance": 560,
"plannedDriveDurationSeconds": 72000,
"driver": {
"loginId": "driver4"
},
"tripStatus": "NOT_STARTED"
}
Creating a custom trip using Geo-Coordinates with IoTFleetMonitoringAdministrator credentials in request
The following example shows the content of the request body in JSON format to create a custom trip using geo-coordinates:
{
"name": "HQ-SFO-SCA-Vehicle_Name",
"source": {
"geoLocation":"37.530705,-122.262420"
},
"destination": {
"geoLocation":"37.391722,-121.952451"
},
"stops": [
{
"geoLocation":"37.794671,-122.401817"
}
],
"vehicle": {
"name": "Vehicle_Name"
}
}
Example of Response Body
The following example shows the content of the response body in JSON format:
{
"id": "DA50A721-5F06-4D3D-ACDB-BE85F10BB696",
"name": "HQ-SFO-SCA-Vehicle_Name",
"driverId": "E8E8B1E4-0D8A-4ECB-95CA-A555510D3D49",
"vehicleId": "9E921611-F05A-4356-BE40-107E63CA480F",
"source": {
"address": "500 Oracle Parkway::Redwood City::CA::US::94065",
"geoLocation": [
-122.26223,
37.53084
],
"estimatedTimeToNextStop": 1945,
"distanceToNextStop": 23.997354694103965,
"expectedDurationFromStart": 0,
"city": "Redwood City",
"country": "US",
"plannedArrivalTime": 1519811366198,
"plannedDepartureTime": 1519811366198,
"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": 1519984166198,
"plannedDepartureTime": 1519984166198,
"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": 44.78222147367256,
"expectedDurationFromStart": 43200,
"city": "San Francisco",
"country": "US",
"plannedArrivalTime": 1519854566198,
"plannedDepartureTime": 1519854566198,
"postalCode": "94111",
"state": "CA",
"stopDurationInSeconds": 0,
"street": "475 Sansome Street",
"stopSequence": 2
}
],
"tripStatus": "IN_PROGRESS",
"earliestStartTime": 1528957500000,
"latestStartTime": 1528959500000,
"plannedDriveDistance": 560,
"plannedDriveDurationSeconds": 72000,
"expectedDuration": 5046,
"startTime": 1519811366319,
"endTime": -1,
"tripLength": 68.35083089999999,
"lastModifiedTime": 1519811366415,
"stopsCompleted": 0,
"totalStops": 1,
"stopsClassification": "SINGLE_STOP",
"tripLengthClassification": "SHORT",
"tripContext": [
{
"value": "DA50A721-5F06-4D3D-ACDB-BE85F10BB696",
"name": "HQ-SFO-SCA-Vehicle_Name",
"type": "TRIP"
}
],
"links": [
{
"href": "https://iotserver:443/fleetMonitoring/clientapi/v2/trips/",
"rel": "self"
},
{
"href": "https://iotserver:443/fleetMonitoring/clientapi/v2/trips/",
"rel": "canonical"
},
{
"href": "https://iotserver:443/fleetMonitoring/clientapi/v2/vehicles/9E921611-F05A-4356-BE40-107E63CA480F",
"rel": "vehicle"
},
{
"href": "https://iotserver:443/fleetMonitoring/clientapi/v2/drivers/E8E8B1E4-0D8A-4ECB-95CA-A555510D3D49",
"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'
-d '{"latestStartTime":1469184297746,"earliestStartTime":1469184297746,"tripTemplateId":"4405245527b4-2a21","driver":{"loginId":"46e562a334c5-72e6","name":"Name of the driver associated with this trip","externalId":"4e3275d817-2e0c"},"name":"Trip name","destination":{"country":"Name of country","stopDurationInSeconds":12345,"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","plannedArrivalTime":1469184297746,"postalCode":"Postal/Zip code","expectedDurationFromStart":12345,"plannedDepartureTime":1469184297746,"timeZone":"Time zone of the time fields","geoLocation":{"valid":false,"altitude":0.0,"latitude":0.0,"longitude":0.0,"additionalElements":["additionalElements_1","additionalElements_2","additionalElements_3"]},"street":"Name of Street","state":"Name of State"},"source":{"country":"Name of country","stopDurationInSeconds":12345,"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","plannedArrivalTime":1469184297746,"postalCode":"Postal/Zip code","expectedDurationFromStart":12345,"plannedDepartureTime":1469184297746,"timeZone":"Time zone of the time fields","geoLocation":{"valid":false,"altitude":0.0,"latitude":0.0,"longitude":0.0,"additionalElements":["additionalElements_1","additionalElements_2","additionalElements_3"]},"street":"Name of Street","state":"Name of State"},"stops":[{"country":"Name of country","stopDurationInSeconds":12345,"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","plannedArrivalTime":1469184297746,"postalCode":"Postal/Zip code","expectedDurationFromStart":12345,"plannedDepartureTime":1469184297746,"timeZone":"Time zone of the time fields","geoLocation":{"valid":false,"altitude":0.0,"latitude":0.0,"longitude":0.0,"additionalElements":["additionalElements_1","additionalElements_2","additionalElements_3"]},"street":"Name of Street","state":"Name of State"}],"expectedDuration":12345,"plannedDriveDistance":12345,"plannedDriveDurationSeconds":12345,"vehicle":{"name":"Name of the vehicle assigned to the trip"}}'
https://iotserver/fleetMonitoring/clientapi/v2/trips
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.