Back to Documentation Overview

Scheduled tasks

There are times when we have prior information of all the tasks we want to complete in the future. In such cases, we can schedule tasks using Time Windows.

This guide will cover all the steps of scheduling tasks while simultaneously catering to on-demand tasks using the Dispatch API. We will:

  1. Create a fleet and a vehicle
  2. Create a scheduled task
  3. Create an on-demand task
  4. Complete the on-demand task
  5. Complete the scheduled task
  6. 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

We will create a vehicle in the fleet with information such as vehicle ID, capacity, initial position, and it's state that it is accepting assignments.

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-test","fleetId":"fleet-test","vehicleCapacities":[{"capacityType":"seats","value":4}]},"initialPosition":{"position":{"position":{"latitude":37.79041302,"longitude":-122.3921746},"heading":0}},"initialVehicleState":{"acceptingAssignments":true}}'

Step 2: Create a scheduled task (task-1)

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 can set the time such that the passenger/item pick up is scheduled 30 minutes from now, and should happen no later than 35 minutes.

Before running the below command, please update the two timestamps such that they are in the future and in UTC.

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-1","fleetId":"fleet-test","taskDefinition":{"pickupDropoffTask":{"uniqueResourcePickup":{"pickupLocation":{"position":{"latitude":37.794682,"longitude":-122.41148}},"uniqueResource":{"requiredCapacities":[{"capacityType":"seats","value":2}],"metadata":{"data":{"rider-name":"Rider test 1","rider-phone":"123-4567","rider-url":"web.com"}}}},"dropoff":{"position":{"latitude":37.802372,"longitude":-122.418729}}},"dispatchParameters":{"requiredPickupTimeWindow":{"earliestTime":"2020-08-10T19:24:59Z","latestTime":"2020-08-10T19:54:59Z"}},"requestorId":"rider-1"}}'

Get state of the task

We can get the current state of the task by using the GetTask endpoint. The vehicle 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-1"}'

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: Create an on-demand task (task-2)

Now, we will request another task to simulate an on-demand request received in real time. The drop-off time of this task is same as the pick-up time of the scheduled task and has been set using the requiredDropoffTimeWindow field. The vehicle will be assigned to this task only if the task can be completed before the scheduled task begins.

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-2","fleetId":"fleet-test","taskDefinition":{"pickupDropoffTask":{"uniqueResourcePickup":{"pickupLocation":{"position":{"latitude":37.790329,"longitude":-122.392231}},"uniqueResource":{"requiredCapacities":[{"capacityType":"seats","value":2}],"metadata":{"data":{"rider-name":"Rider test 2","rider-phone":"123-4567","rider-url":"web.com"}}}},"dropoff":{"position":{"latitude":37.795107,"longitude":-122.393426}}},"dispatchParameters":{"requiredDropoffTimeWindow":{"latestTime":"2020-08-10T19:24:59Z"}},"requestorId":"rider-2"}}'

Get state of the task

Since this task can be completed before the pick-up time of the scheduled task, the vehicle will be assigned to this task as well and is 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-2"}'

Step 4: Complete the on-demand task (task-2)

We will complete the on-demand 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-2","stepToComplete":[{"stepId":"0807da2f-0b00-4323-91ac-839d0ec825f1"},{"stepId":"7add6cae-069e-4cfd-8f84-620fabe5566b"},{"stepId":"4c48ef2f-c035-4ed0-b554-c77a7580bf74"},{"stepId":"12aff92f-5cb4-4139-b188-5d5879a59744"}]}'

Step 5: Complete the scheduled task (task-1)

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-1","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 6: 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-test"}'

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: