Back to Documentation Overview

Mobile Warehouse delivery with Dispatch API

This guide will cover all the steps of using generic resources in order to do a mobile warehouse style delivery with the Dispatch API. We will:

  1. Create a generic resource
  2. Create a fleet
  3. Create a vehicle and add the generic resource to its inventory
  4. Create a task to drop off the generic resource
  5. Get the state of the task
  6. Complete all the steps of the task
  7. Clean up the vehicle and the fleet

Generic resources are resources that are interchangeable with other identical resources. For more information on resources and types of resources, please refer to this guide.

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 generic resource

We will create a generic resource by using the CreateGenericResource endpoint of the Resource API. In this example, the generic resources are boxes containing identical items.

curl --request POST https://api.rideos.ai/dispatch-resources/preview/CreateGenericResource \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"resource":{"resourceId":"resource-box","requiredCapacities":[{"capacityType":"box","value":1}]}}' 

Step 2: Create a fleet

Now we will create a fleet.

curl --request POST https://api.rideos.ai/dispatch-fleets/preview/CreateFleet \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{ "fleet": { "fleetId": "fleet-test"} }' 

Step 3: Create a vehicle in the fleet and add the generic resource to its inventory

We will create a vehicle in the fleet. The vehicleCapacities field refers to the types of capacities supported by the vehicle such as seats, boxes, weight etc. A vehicle can have more than one type of capacity. In this example, the car has the capacity to carry 10 boxes. Inventory refers to the generic resources that a vehicle is currently carrying. In this example, the car is currently carrying 5 boxes. The inventory can be updated by the UpdateVehicle endpoint of the Vehicle API.

curl --request POST https://api.rideos.ai/dispatch-vehicles/preview/CreateVehicle \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"vehicle":{"vehicleId":"vehicle-resources","fleetId":"fleet-test","vehicleCapacities":[{"capacityType":"box","value":10}],"inventory":{"resources":[{"resourceId":"resource-box","count":5}]}},"initialPosition":{"position":{"position":{"latitude":37.79041302,"longitude":-122.3921746},"heading":0}},"initialVehicleState":{"acceptingAssignments":true}}' 

Step 4: Create a task to drop off the generic resource

Since this is a mobile warehouse style of delivery, the vehicle already has the resources in its inventory. While creating a task, we will set the generic resource that needs to be dropped off at the destination. In this example, we will drop off 2 boxes at the destination. Any vehicle that has the requested resource in its inventory is capable of making the delivery and will be taken into consideration by the optimization algorithm.

curl --request POST https://api.rideos.ai/dispatch-tasks/preview/CreateTask \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"taskId":"task-resources","fleetId":"fleet-test","taskDefinition":{"pickupDropoffTask":{"dropoff":{"position":{"latitude":37.802372,"longitude":-122.418729}},"genericResourcePickup":{"genericResourceGroup":{"genericResources":[{"resourceId":"resource-box","count":"2"}]}}},"requestorId":"rider-1"}}'

Step 5: 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/preview/GetTask \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"taskId": "task-resources"}' 

In the response, we will also get the step IDs as well as the states of the steps required to successfully complete the task i.e drive to pick-up location, pick up the resource, drive to destination, and drop off the resource. The driveToPickup and pickupResource steps are in completed state as the vehicle already has the resources in its inventory.

Step 6: Complete the steps of the task

We will complete the task by using the CompleteSteps endpoint and the stepIDs of driveToDropoff and dropoffResource steps returned in the response of GetTask.

curl --request POST https://api.rideos.ai/dispatch-tasks/preview/CompleteSteps \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"taskId":"task-resources","stepToComplete":[{"stepId":"0807da2f-0b00-4323-91ac-839d0ec825f1"},{"stepId":"7add6cae-069e-4cfd-8f84-620fabe5566b"}]}' 

Step 7: Remove the vehicle and the 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/preview/DeleteVehicle \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"vehicleId":"vehicle-resources"}' 

Delete fleet

We will delete the fleet by using the DeleteFleet endpoint of Fleet API.

curl --request POST https://api.rideos.ai/dispatch-fleets/preview/DeleteFleet \
--header "Content-Type: application/json" \
--header "X-Api-Key: $RIDEOS_API_KEY" \
--data '{"fleetId":"fleet-test"}' 

We have successfully created a generic resource, added it to the vehicle's inventory, and completed the delivery. You may also want to: