Fuel API
- Phil Windley
The Fuel API provides queries and events for interacting with the services that comprise it.
Calculations
The Fuel API calculates values like distance between fillups and MPG using a very simply formula that always assumes that fillups are recorded in sequence. It doesn't try to recalculate sequences based on entered timestamps.
Units
The Fuel API is unitless. It depends on the developer to consistently record the same units for the application.
Return Results
The Fuel API returns fuel details. A fillup record contains the following data fields
| Name | Type | Calculated | Description |
| id | Integer | yes | The internal system identifier for this trip. Uses time the record is created as key. |
| timestamp | DateTime | The time of the purchase. Can be given or calculated. | |
| volume | Float | no | Volume of the fillup |
| unit_price | Float | no | price for a unit of fuel |
| cost | Float | yes | Total cost of the fillup |
| location | String | no | The location of the fillup |
| odometer | Float | no | Odometer reading at fillup |
| distance | Float | yes | Distance between this fillup and the last |
| mpg | Float | yes | Distance per fuel unit based on distance |
| interval | Integer | yes | Seconds between this fill up and the last |
DateTime is an ISO8901 formatted time. Returned times are always UTC
Queries
| development | b16x20 |
|---|---|
| production | fuse_fuel |
The production version is always pre-pended to the production query domain with a underbar, so for version 1 of the API would use v1_fuse_fuel as the query domain. In this document we will use the production query domain without the version. See Fuse Base URLs for more information on how to turn the descriptions shown here into a query URL.
fuse_fuel:fillups([<id>])
Query fillups. All parameters are optional. With <id>, the detailed fillup data for a specific fillup is returned. Without <id>, detailed data for the last fillup is returned.
For example, to return the ten most recent fillups, you would simply for the following:
fuse_fuel:fillups()
To return the data for last fillup:
fuse_fuel:fillups()
fuse_fuel:fillupsByDate(<start>, <end>)
Query past fillups for those between a start and end time. Summary fillup data is returned. Times are expressed in ISO8901 format.
For example to find all the fillups for June 2014 in the US Mountain time zone:
fuse_fuel:fillupsByDate(start="20140601T000000-0600", end="20140701T000000-0600")
Events
The following events are used defined for fillups in the Fuse API.
fuse:new_fuel_purchase
A new fillup has been detected with the following attributes:
| Name | Type | Description |
| volume | Float | Volume of the fuel purchase |
| unit_price | Float | price for a unit of fuel |
| location | String | The location of the fuel purchase |
| odometer | Float | Odometer reading at fuel purchase |
| when_bought | DateTime | Time when fuel was purchase |
fuse:updated_fuel_purchase
An updated fillup has been detected with the following attributes:
| Name | Type | Description |
| id | DateTime | id for the record to update |
| volume | Float | Volume of the fuel purchase |
| unit_price | Float | price for a unit of fuel |
| location | String | The location of the fuel purchase |
| odometer | Float | Odometer reading at fuel purchase |
| when_bought | DateTime | Time when fuel was purchase |
fuse:unneeded_fuel_purchase
Delete the fuel purchase record with the given id.
| Name | Type | Description |
| id | DateTime | id for the record to delete |
Services
fuse_fuel:record_fuel_purchase
Selector:
select when fuse new_fuel_purchase
Synopsis:
Records a new fuel purchase. Uses fuse_fuel:update_fuel_purchase
Raises:
fuse:updated_fuel_purchase
fuse_trips:update_fuel_purchase
Selector:
select when fuse updated_fuel_purchase
Synopsis:
Updates a fuel purchase.
Raises:
none
fuse_trips:delete_fuel_purchase
Selector:
select when fuse unneeded_fuel_purchase
Synopsis:
Deletes the fuel purchase for a given ID
Raises:
none