Scheduled tasks
There are times when we have prior information of all the tasks and vehicles and want to schedule tasks i.e., compute the optimization plan and assign vehicles to tasks in advance. In such cases, we can schedule tasks using Time Windows and Vehicle Shifts.
This guide will cover all the steps of scheduling tasks using the Dispatch API. We will:
- Create a fleet and a vehicle
- Create a scheduled task
- Complete the scheduled task
- Delete vehicle and fleet
Prerequisite: Get the API Key
To run this example, you will need a rideOS API Key. You can sign up for one here and view it on your profile page.
Once you have the API Key, you can set the environment variable with export RIDEOS_API_KEY="YOUR_API_KEY" and use RIDEOS_API_KEY in the cURL commands given below.
Step 1: Create a fleet and a vehicle
We will first create a fleet and add a vehicle to the fleet. For more information, please refer to Fleet API and Vehicle API.
Create a fleet
curl --request POST https://api.rideos.ai/dispatch-fleets/v3/CreateFleet \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{ "fleet": { "fleetId": "fleet-test"} }' Create a vehicle in the fleet
As an example, let's say that a driver is available only for the evening shift from 5pm to 8pm. In such a case, we will specify the shift while creating the vehicle. Only tasks, both on-demand or scheduled, that can be completed (pick-up and drop-off) between 5pm and 8pm will be assigned to this vehicle. When the vehicle shift is specified, it is mandatory to specify the initial position of the vehicle.
Before running the below command, please update the shiftTimeWindow such that they are in the future and in UTC.
curl --request POST https://api.rideos.ai/dispatch-vehicles/v3/CreateVehicle \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{
"vehicle": {
"vehicleId": "vehicle-with-shift",
"fleetId": "fleet-test",
"vehicleCapacities": [
{
"capacityType": "seats",
"value": 4
}
],
"shiftConstraint": {
"expectedStartTime": "2020-11-18T17:00:00Z",
"expectedEndTime": "2020-11-18T20:00:00Z"
}
},
"initialPosition": {
"position": {
"position": {
"latitude": 37.791,
"longitude": -122.392
},
"heading": 0
}
},
"initialVehicleState": {
"acceptingAssignments": true
}
}'Step 2: Create a scheduled task
We will schedule a task by using requiredPickupTimeWindow field in the CreateTask endpoint of the Task API.
Create a task
We will set the earliestTime and latestTime of the requiredPickupTimeWindow to schedule tasks in the future.
In this example, we have set the time such that the passenger/item pick-up is scheduled between 5:30pm and 5:40pm.
Before running the below command, please update the two timestamps such that they are within the start and end time of the vehicle shift.
curl --request POST https://api.rideos.ai/dispatch-tasks/v3/CreateTask \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{
"taskId": "task-scheduled",
"fleetId": "fleet-test",
"taskDefinition": {
"pickupDropoffTask": {
"uniqueResourcePickup": {
"pickupLocation": {
"position": {
"latitude": 37.795,
"longitude": -122.411
}
},
"uniqueResource": {
"requiredCapacities": [
{
"capacityType": "seats",
"value": 2
}
],
"metadata": {
"data": {
"rider-name": "Rider test 1",
"rider-phone": "123-4567"
}
}
}
},
"dropoff": {
"position": {
"latitude": 37.802,
"longitude": -122.418
}
}
},
"dispatchParameters": {
"requiredPickupTimeWindow": {
"earliestTime": "2020-11-18T17:30:00Z",
"latestTime": "2020-11-18T17:40:00Z"
}
},
"requestorId": "rider-1"
}
}' Get state of the task
We can get the current state of the task by using the GetTask endpoint. The vehicle vehicle-with-shift has been assigned to the task as denoted by assignedVehicleId.
curl --request POST https://api.rideos.ai/dispatch-tasks/v3/GetTask \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"taskId": "task-scheduled"}' In the response, we will also get the step IDs of the next steps required to successfully complete the trip i.e drive to pick-up location, pick up the resource, drive to destination, and drop off the resource.
Step 3: Complete the scheduled task
We will complete the scheduled task by using the CompleteSteps endpoint and the stepIDs returned in the response of GetTask.
curl --request POST https://api.rideos.ai/dispatch-tasks/v3/CompleteSteps \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"taskId":"task-scheduled","stepToComplete":[{"stepId":"93070a0f-a84f-49e2-80e4-cf24b1d45d94"},{"stepId":"20f3fe48-cbc5-4bda-b703-ac5112fb2635"},{"stepId":"09d77f60-3775-4d44-968d-204ba45324c3"},{"stepId":"4fd3eeaa-0cf2-4d16-83f2-9e7abf4338cd"}]}' Step 4: Delete vehicle and fleet
We will first delete the vehicle and then delete the fleet.
Delete vehicle
We will delete the vehicle by using the DeleteVehicle endpoint of Vehicle API.
curl --request POST https://api.rideos.ai/dispatch-vehicles/v3/DeleteVehicle \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"vehicleId":"vehicle-with-shift"}' Delete fleet
We will delete the fleet by using the DeleteFleet endpoint of Fleet API.
curl --request POST https://api.rideos.ai/dispatch-fleets/v3/DeleteFleet \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"fleetId":"fleet-test"}' We have successfully used the Dispatch API to schedule tasks using time windows. You may also want to check out: