Scheduled tasks

Schedule Tasks in Advance

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: