Create trip
post
/fleetMonitoring/clientapi/v2/trips
This operation creates a new trip. To create a default trip, provide {vehicle.name and tripTemplateId} as request parameters. To create a custom trip, provide {vehicle.name, source, destination, and stops} as request parameters.
Permissions
To create a trip the request must have driver role credentials.
Permissions
To create a trip the request must have driver role credentials.
Request
Supported Media Types
- application/json
- application/vnd.oracle.resource+json;type=singular
Root Schema : Trip_create
Type:
Show Source
object
-
destination:
object TripStops_create
-
name:
string
Trip name
-
source:
object TripStops_create
-
stops:
array stops
List of stops for the trip
-
tripTemplateId:
string
ID of the tripTemplate associated with the trip
-
vehicle:
object Vehicle_create
Nested Schema : TripStops_create
Type:
Show Source
object
-
address:
string
Unified full address, e.g. 500 Oracle Parkway::Redwood City::CA::US::94065 . Must be provided if geoLocation is not specified.
-
city:
string
Name of City
-
country:
string
Name of country
-
distanceToNextStop:
number
Estimated distance to next stop
-
expectedDurationFromStart:
integer
Expected duration to reach from Start to this Stop (second)
-
geoLocation:
object GeoPosition_create
-
postalCode:
string
Postal/Zip code
-
state:
string
Name of State
-
stopSequence:
integer
Property description was not set
-
street:
string
Name of Street
-
timeZone:
string
Time zone of the time fields
Nested Schema : Vehicle_create
Type:
Show Source
object
-
id:
string
vehicle ID
-
name:
string
vehicle name
-
registrationNumber:
string
vehicle registration number
Nested Schema : GeoPosition_create
Type:
Show Source
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
Supported Media Types
- application/json
- application/vnd.oracle.resource+json;type=singular
202 Response
Successfully processed.
Root Schema : Trip_receive
Type:
Show Source
object
-
destination:
object TripStops_receive
-
driverId:
string
ID of the driver associated with the trip
-
endTime:
integer
Trip end time (millisecond)
-
expectedDuration:
integer
Expected duration of the Trip (second)
-
id:
string
Trip ID
-
lastModifiedTime:
integer
Last modified time (millisecond)
-
name:
string
Trip name
-
source:
object TripStops_receive
-
startTime:
integer
Trip start time (millisecond)
-
stops:
array stops
List of stops for the trip
-
stopsClassification:
string
One of [SINGLE_STOP, DUAL_STOP, TRIPLE_STOP, MULTI_STOP, NON_STOP].
-
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 [IN_PROGRESS, COMPLETED, CANCELLED].
-
tripTemplateId:
string
ID of the tripTemplate associated with the trip
-
vehicle:
object Vehicle_receive
-
vehicleId:
string
ID of the vehicle associated with this trip
Nested Schema : TripStops_receive
Type:
Show Source
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 to reach from Start to this Stop (second)
-
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
Property description was not set
-
stopType:
string
The reason for stopping
-
street:
string
Name of Street
-
timeZone:
string
Time zone of the time fields
Nested Schema : Vehicle_receive
Type:
Show Source
object
-
id:
string
vehicle ID
-
name:
string
vehicle name
-
registrationNumber:
string
vehicle registration number
Nested Schema : GeoPosition_receive
Type:
Show Source
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
Nested Schema : TripContext_receive
Type:
Show Source
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
Bad Request. The request could not be understood by the server due to malformed syntax. The client SHOULD NOT repeat the request without modifications.
401 Response
Unauthorized. The request requires user authentication.
403 Response
Forbidden. The server understood the request, but is refusing to fulfill it. Authorization will not help and the request SHOULD NOT be repeated.
406 Response
Not Acceptable. The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.
415 Response
Unsupported Media Type. The request entity has a media type which the server or resource does not support.
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
Creating a trip using Trip Template
The following example shows the content of the request body in JSON format to create a trip using a trip template:
{
"tripTemplateId": "1A7FF827-5481-4188-8BC3-F1E96A5CC9ED",
"vehicle": {
"name": "Vehicle_Name"
}
}
Creating a custom trip using addresses
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"
}
}
Creating a custom trip using Geo-Coordinates
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",
"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 '{"tripTemplateId":"147a26ee5876-55d0","name":"Trip name","destination":{"distanceToNextStop":0.0,"country":"Name of country","stopSequence":12345,"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","postalCode":"Postal/Zip code","expectedDurationFromStart":12345,"timeZone":"Time zone of the time fields","state":"Name of State"},"source":{"distanceToNextStop":0.0,"country":"Name of country","stopSequence":12345,"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","postalCode":"Postal/Zip code","expectedDurationFromStart":12345,"timeZone":"Time zone of the time fields","state":"Name of State"},"stops":[{"distanceToNextStop":0.0,"country":"Name of country","stopSequence":12345,"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","postalCode":"Postal/Zip code","expectedDurationFromStart":12345,"timeZone":"Time zone of the time fields","state":"Name of State"}],"vehicle":{"registrationNumber":"vehicle registration number","name":"vehicle name","id":"1165280e1be2-6249"}}'
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.