Calculate Deadhead

POST/scheduling/deadhead

Calculate empty vehicle travel (deadhead) between assigned trips. Deadhead is the distance/time a vehicle travels without passengers - from home to first pickup, and between consecutive trips.

Request Body

Field	Type	Required	Description
`trips`	Trip[]	Yes	Trips with full stop data and vehicle assignments
`cars`	Vehicle[]	Yes	Vehicles with home locations

Trip

Field	Type	Required	Description
`id`	string	Yes	Trip identifier
`carId`	string	Yes	Assigned vehicle ID
`date`	ISO8601	Yes	Trip start time
`duration`	number	Yes	Total duration (seconds)
`distance`	number	Yes	Total distance (meters)
`seats`	number	Yes	Seats required
`stops`	Stop[]	Yes	Trip stops with times and locations

Stop

Field	Type	Required	Description
`loc`	Coordinates	Yes	Stop location
`date`	ISO8601	Yes	Scheduled arrival time
`name`	string	No	Stop name/address

Coordinates

Field	Type	Required	Description
`lat`	number	Yes	Latitude
`lng`	number	Yes	Longitude

Vehicle

Field	Type	Required	Description
`id`	string	Yes	Vehicle identifier
`seats`	number	Yes	Total seat capacity
`attr`	string[]	Yes	Vehicle attributes
`addrLoc`	Coordinates	Yes	Home/starting location

Example Response

{
  "deadheads": [
    {
      "vehicleId": "car_1",
      "segments": [
        {
          "fromTrip": null,
          "toTrip": "trip_1",
          "distance": 1200,
          "duration": 300,
          "gap": 0
        },
        {
          "fromTrip": "trip_1",
          "toTrip": "trip_2",
          "distance": 2100,
          "duration": 480,
          "gap": 1320
        }
      ],
      "totalDistance": 3300,
      "totalDuration": 780
    }
  ]
}

Deadhead Segment Fields

Field	Type	Description
`fromTrip`	string	null
`toTrip`	string	Next trip ID
`distance`	number	Empty travel distance (meters)
`duration`	number	Empty travel time (seconds)
`gap`	number	Wait time before next trip (seconds)

Summary Fields

Field	Type	Description
`vehicleId`	string	Vehicle identifier
`segments`	DeadheadSegment[]	Empty travel segments
`totalDistance`	number	Total deadhead distance (meters)
`totalDuration`	number	Total deadhead time (seconds)

Use Cases

Cost Analysis: Calculate non-revenue miles for cost reporting
Efficiency Metrics: Measure fleet utilization efficiency
Assignment Optimization: Compare deadhead across assignment options
Driver Compensation: Calculate paid non-driving time

On this page