Sign in Talk to us Free trial
Free trial

Design and software studio
Colour

Fuel economy

Record fuel fills and read an asset's fuel economy from full-to-full segments, with every excluded segment labelled.

For
OwnerFleet managerDriver
Hosting
Any hosting
Devices
All devices
Business
Fleet

Checked against Pop Street Dispatch 0.1.0

You will be able to record every fuel fill for an asset and read its fuel economy for any period. Dispatch works the figure out from the stretch between two full fills, and it keeps every stretch it cannot use on the list with a plain label.

Before you start #

  • The dispatch_fleet licence flag is on for your account (it is in the Business plan, an add-on for Starter and Pro, and included in the 14-day trial).
  • The asset exists and has an odometer, or an hours meter for equipment that counts hours only.
  • Fuel is entered in the volume unit of your business (set in your locale settings). Each fill can carry its own volume_unit: l, gal_us or gal_uk.

Steps #

  1. Send POST /fleet/assets/:id/fuel for each fill with volume, odometer (or hours), full_tank and, when you have the receipt, total_cents and tax_cents. The answer holds the new id and, when a total was given, the expense_id of the linked expense.
  2. Leave full_tank as true for a full fill. Send false for a part fill, which joins the volume of its stretch.
  3. Send missed_prior: true when you know an earlier fill was never recorded.
  4. Read the result with GET /fleet/assets/:id/fuel/economy. Add from and to to choose the period, and basis=hours for hours-only equipment.
  5. Look at each segment: economy holds the figure, included says whether it counts, and excluded_label gives the reason in words when it does not.

How a figure is worked out #

A segment runs from one full fill to the next. Its volume is every fill after the first one, up to and including the closing fill. Its distance is the odometer difference between the two fills. The fill that opens the segment gives only its odometer reading, so its litres belong to the segment before it.

For distance, the economy is litres per 100 km in hundredths, shown in the units of your business. For hours-only equipment, the economy is litres per hour in hundredths, and span is hours in hundredths.

A period report adds up the usable segments whose closing fill falls in the period. It also lists the fuel that no usable segment accounts for (unmatched_volume_ml) and the distance covered in excluded segments (unattributed_span), apart from the economy.

Why a segment is excluded #

Dispatch never deletes a segment. It marks it excluded and shows the label below.

CodeLabel shown
missed_priorA fill-up before this one was not recorded.
no_odometerA fill-up has no odometer reading.
order_conflictThe odometer readings and the dates do not agree.
span_too_shortToo little distance to give a meaningful figure.
volume_too_smallToo little fuel to give a meaningful figure.
outlierFar from this asset's usual figures.

When a fill has no reading of its own, Dispatch reads the value from the meter log at that moment. The segment then counts and carries the note "Estimated from the meter log."

Technical details
  • Limits in force: at least 10 km of distance (or 1.00 hour), at least 5 litres of fuel, and for the outlier test at least 4 other usable segments for the same asset. A segment is an outlier when its modified z-score against the asset's other segments is above 3.5.
  • The fuel log is the record that counts. The expense row created with a fill is a view linked by a unique fuel_log_id. To change a fuel expense, correct the fuel fill. Voiding the linked expense directly returns conflict.
  • A fill with an odometer writes a meter reading with source fuel.

If something goes wrong #

  • feature_not_licensed (403): the Fleet flag is off. Reads and exports keep working.
  • licence_read_only (403): the licence is in read-only state. Renew it, then record the fill again.
  • validation_failed (422): volume is missing or zero, paid_by holds a value other than company, driver or account, or volume_unit is unknown.
  • invalid_date (422): filled_at needs the form of an ISO 8601 date-time.
  • not_found (404): no asset has that id.
  • A segment you expected to count is excluded: read its excluded_label, fix the cause (add the missing odometer, or record the missing fill), and read the economy again.