Back to Documentation Overview

Ridehail Service with Dispatch API

This guide will cover all the steps of creating a simple ridehail service using the Dispatch API. We will:

  1. Create a fleet and add a vehicle to the fleet.
  2. Create a task with a unique resource, i.e. passengers.
  3. Get current state of the task, including the step completion state.
  4. Complete all the steps of the task, i.e. help the passenger go from one location to another.
  5. Delete vehicle and fleet.

Please refer to the guides on Tasks and Resources for more information.

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/preview/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, and initial position. The vehicle is initialized to accept assignments. In this example, the vehicle has a capacity of 4 seats and thus can accommodate 4 passengers.

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-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 task with unique resource

We will create a task using the CreateTask endpoint of the Task API. In this example, the unique resource refers to 2 passengers who want to travel from one location to another. Thus, the the capacityType is seats and its value is set to 2.

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-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}}},"requestorId":"rider-1"}}'

In the response, we get the state as inProgress that denotes that the task has steps that need to be completed. The assignment field is missing which means that a vehicle has not been assigned to the task yet. It is recommended to regularly poll the GetTask endpoint after creating the task to get the current state of the task including the assigned vehicle ID and the step completion state.

Step 3: Get current state of the task

We can get the current state of the task and the steps by using the GetTask endpoint. The vehicle assigned to the task is denoted by the assignment field. In case a vehicle could not be assigned, the reason can be found in the unresolvableReason field.

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-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 the pick-up location, pick up the the passenger, drive to the destination, and drop off the passenger.

Step 4: Complete all the steps of the task

We will complete the task by using CompleteSteps endpoint and the stepIDs returned in the response of GetTask. The state of each step is returned both in the response of this method and can also be fetched from the GetTask endpoint. After completing all the steps, the state of the task changes to completed.

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-1","stepToComplete":[{"stepId":"8a23213f-b25b-4d1a-8fe2-12f210151149"},{"stepId":"eb5d2034-abb4-4069-967c-2da6c66f4370"},{"stepId":"824f65ab-4230-4fe9-9389-554b038d66a3"},{"stepId":"65f483fb-3be9-433d-ae45-0a1d99736d08"}]}' 

Step 5: Clean up the fleet and vehicles

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-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/preview/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 create a ridehail service. You may also want to check out: