HOWTO: Change keg levels using the API

Overview

Taplist.io lets you manage your own private database of kegs and show them off on a digital menu.

Although Taplist.io does not directly build or support flow sensors or other keg level monitoring hardware (such as Kegbot and similar projects), keg records in Taplist.io can have a volume recorded against them using the Taplist.io developer API. When you set levels this way, our keg artwork automatically adjusts to it, and you can retrieve the levels with the same API.

Caution: This HOWTO is for advanced users. You should already be comfortable with some level of programming and interacting with APIs like ours.

Data model

Internally, Keg objects support three volume-related concepts, all of which are fields that may be PATCHed:

  • full_volume_ml: The “full” volume of the keg, in milliliters. Initialized automatically when a keg is created, based on its shell type.
  • served_volume_ml: A counter of how much volume has been served. Currently no Taplist.io feature writes to this field, other than user-defined API clients.
  • spilled_ml: A separate counter, analogous to served_volume_ml but for counting non-served volume (spills, pour-outs, etc).

Keg artwork automatically adjusts based on the keg’s fullness, as determined by:

(served_volume_ml + spilled_volume_ml) / full_volume_ml

How to record a pour

Option 1: Set volume directly on keg.

You may PATCH a Keg object to set/replace its volume:

http patch \
  https://taplist.io/api/v1/venues/$VENUE_NAME/kegs/1 \
  Authorization:"token $AUTH_TOKEN" \
  served_volume_ml=1000

A limitation of this method is that you need to know the keg id, and you need to specify the exact served volume.

Option 2: Set volume against a tap

In the future, you will be able to patch the current keg assigned to a tap. This means IoT devices do not need awareness of Keg ids, only tap numbers. Example:

http patch \
  https://taplist.io/api/v1/venues/$VENUE_NAME/taps/1/current-keg \
  Authorization:"token $AUTH_TOKEN" \
  served_volume_ml=1000

Option 3/4: Deduct against a keg/tap

Variations of options 1 and 2, but which support relative deduction rather than absolute setting. IoT devices do not need to read or maintain state of keg volume:

http patch \
  https://taplist.io/api/v1/venues/$VENUE_NAME/kegs/1 \
  Authorization:"token $AUTH_TOKEN" \
  add_served_volume_ml=1000

http patch \
  https://taplist.io/api/v1/venues/$VENUE_NAME/taps/1/current-keg \
  Authorization:"token $AUTH_TOKEN" \
  add_served_volume_ml=1000

Feedback and help

Feel free to reply to this topic with questions or ideas.

1 Like

Just bumping this! Definitely looking forward to any feedback on the developer experience - shout if you have any questions.

Just started with this and a very limited coding experience. I want to use a raspberry pi with a couple buttons that reduce the volume of the associated keg by a fixed amount (1 pint). It won’t provide a perfect volume of beer but it will be a decent ballpark.