Back to Documentation Overview

Capacities in Dispatch API

Capacity refers to the inventory and/or passengers 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.

In this guide, we will go through different use cases of capacities and how they affect dispatch.

1. Single capacity: Pizza delivery

In this example, the vehicle has a single type of capacity i.e., 4 pizza boxes.

We will create a vehicle using the CreateVehicle endpoint. The following snippet can be used in the request to define the capacity of the vehicle:

# Capacity of Vehicle-1:
{
   "vehicleCapacities":[
      {
         "capacityType":"box",
         "value":4
      }
   ]
}

Say we get 2 pizza orders and in total 3 pizza boxes need to be delivered. We will create the tasks using the CreateTask endpoint. The following snippets can be used in the request to define the capacity of the requested resources:

# Pizza order 1
{
   "taskId":"order-1",
   "requiredCapacities":[
      {
         "capacityType":"box",
         "value":2
      }
   ]
}

# Pizza Order 2
{
   "taskId":“order-2”,
   "requiredCapacities":[
      {
         "capacityType":"box",
         "value":1
      }
   ]
}

Vehicle-1 can complete both the deliveries as it has a maximum capacity of 4 boxes.

2. Interchangeable capacities: Ridehail with car seat

In this example, the vehicle has a maximum capacity of 4 seats with a provision to install a car seat for children. Thus, the vehicle can carry a maximum of 4 adults or 3 adults and 1 child.

# Capacity of Vehicle-1
{
   "vehicleCapacities":[
      {
         "capacityType":"seats",
         "value":4
      },
      {
         "capacityType":"car_seat",
         "value":1
      }
   ]
}

Say we get a trip request for 2 adults

# Trip 1
{
   "taskId":“trip-1”,
   "requiredCapacities":[
      {
         "capacityType":"seats",
         "value":2
      }
   ]
}

Vehicle-1 can complete this trip as it has a maximum capacity of 4 seats. Once the passengers of this trip have been picked up, there are 2 seats remaining in the vehicle.

Say we get another trip request with 1 adult and 1 child that requires a car seat. Since the car seat goes on top of a normal seat, we will request for 2 seats and 1 car seat to block off the appropriate capacity.

# Trip 2
{
   "taskId":“trip-2”,
   "requiredCapacities":[
      {
         "capacityType":"seats",
         "value":2
      },
      {
         "capacityType":"car_seat",
         "value":1
      }
   ]
}

Vehicle-1 can complete this trip too. Once the passengers of this trip have been picked up, the vehicle doesn't have space to accomodate more passengers.

3. Non-interchangeable capacities: Cake delivery

In this example, the vehicle has storage space built for a specific purpose. Let's say we need to deliver 2 types of cakes - frosted cake and ice cream cake. Ice cream cakes must be frozen during the delivery while frosted cakes must not be frozen as the frosting will become hard. The delivery vehicle has a mini fridge which can hold 4 cakes and special storage in the trunk to hold 6 cakes.

# Capacity of Vehicle-1
{
   "vehicleCapacities":[
      {
         "capacityType":"freezer",
         "value":4
      },
      {
         "capacityType":"cake_storage",
         "value":6
      }
   ]
}

Say we need to deliver a frosted cake. Since this cake will go in the cake storage, we will send the following request:

# Order 1
{
   "taskId":“order-1”,
   "requiredCapacities":[
      {
         "capacityType":"cake_storage",
         "value":1
      }
   ]
}

Now we need to deliver 1 frosted cake and 1 ice cream cake,

# Order 2
{
   "taskId":“order-2”,
   "requiredCapacities":[
      {
         "capacityType":"freezer",
         "value":1
      },
      {
         "capacityType":"cake_storage",
         "value":1
      }
   ]
}

Vehicle-1 can fulfill both these tasks as it has the necessary storage. After picking up the cakes, Vehicle-1 can carry 3 more ice cream cakes and 4 more frosted cakes.

4. Multiple unrelated capacities: Jewelry delivery

Let’s consider a jewelry delivery service where the vehicle has a safe which can carry 5 cases of jewelry. Apart from the space limit, we have a limit of $1000 on the total value of the merchandise per vehicle in order to limit liability.

# Capacity of Vehicle-1
{
   "vehicleCapacities":[
      {
         "capacityType":"case",
         "value":5
      },
      {
         "capacityType":"money",
         "value":1000
      }
   ]
}

Say, we have to deliver a gold and platinum ring worth $300 and $400 respectively.

# Delivery 1
{
   "taskId":“gold-earring",
   "requiredCapacities":[
      {
         "capacityType":"case",
         "value":1
      },
      {
         "capacityType":"money",
         "value":300
      }
   ]
}

# Delivery 2
{
   "taskId":“platinum-earring",
   "requiredCapacities":[
      {
         "capacityType":"case",
         "value":1
      },
      {
         "capacityType":"money",
         "value":400
      }
   ]
}

Vehicle-1 can accomplish these tasks. Say we get another request to deliver a diamond ring worth $800.

{
   "taskId":“diamond-earring",
   "requiredCapacities":[
      {
         "capacityType":"case",
         "value":1
      },
      {
         "capacityType":"money",
         "value":800
      }
   ]
}

Even though the car has 3 more cases to carry jewelry in, this task won't be assigned to Vehicle-1 as it is limited by the total value of merchandise and can only carry jewelry worth $300 more.