Back to Documentation Overview

Introduction to Dispatch APIs

The Dispatch APIs take care of all of your routing, dispatch, and optimization needs, allowing you to focus on the other parts of your business. The API supports a wide range of use cases from ridehail to delivery services, is basemap agnostic, and is compatible with both human-driven and autonomous vehicles.

To setup the most minimal service using the Dispatch API we have to do the following things:

  1. We need to create a fleet using the Fleet API.
  2. We need to create at least one vehicle using the Vehicle API.
  3. Depending on our use-case, we need to create appropriate tasks using the Task API. This could be an incoming ride or package delivery.
  4. We can continiously pull the state of a task to monitor its progesss and/or complete steps using the Task API.
  5. Once we are done we can clean up using the Vehcile API and Fleet API again to delete our vehicle and fleet.

Tasks

Tasks refer to actions that are be completed by the Dispatch API. In terms of ridehail, it can refer to trips from one location to another while for delivery services, it can refer to packages that need to be taken from Point A to Point B.

There are 4 steps a task needs to go through to be completed. These steps are:

  1. Drive to the pick-up location
  2. Pick up the resource
  3. Drive to the drop-off location
  4. Drop off the resource

The current state of the task can be fetched from the GetTask endpoint of the Task API. A task can have 3 states:

  1. In progress means that a task has steps that need to be completed. If the assignment field is not set, it means that a vehicle has not yet been assigned to the task. We can refer to the states of the steps to see how far along the task is in being completed.
  2. Completed means that a task has been completed. The time of completion is also returned in the response.
  3. Cancelled means that a task has been cancelled. The source of cancellation and its description is returned in the response.

Along with the states of the task, the GetTask endpoint also returns the states of all the steps. The state is defined by the boolean field completed which tells us whether the step has been completed or not. Along with the state, we also return the timestamp of when the step was completed. If it has not been completed yet, we return the expected time of completion which can be used to show ETAs to the users.

You can use this cURL command to fetch the current state of the task and steps:

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"}' 

Resources

A resource represents any entity that can be picked up or dropped off. In terms of ridehail, it can refer to passengers and in terms of delivery it can refer to things like packages, boxes, food parcels etc. Using the Dispatch API, we can create and complete tasks to move a resource from one location to another.

There are two types of resources:

Capacities

Capacities refer to the type and number of resources a vehicle can carry. In the Dispatch API, capacity consists of a type and a value. Capacity types, for example, can be "seats", "boxes" or "weight". The value defines the number of units, for example, 4 seats, 10 boxes, 15 kg. It is possible for a vehicle to have multiple types of capacities.

Each resource is associated with a required capacity i.e., the capacity it will occupy within a vehicle. While assigning a vehicle to a task, the optimization algorithm takes into account the resource's required capacity as well as a vehicle's maximum capacity to ensure that this capacity is never exceeded.

For some more example, see this guide on vehicle capacities.

Next steps

To use the the Dispatch API, you will first 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 all the cURL commands given in the documentation.

Here are some guides to get you started with the Dispatch API: