Units

Commands take an amount as two fields: a number and a unit ID from the table below. The number is more than 0 and at most 1,000,000. Send the ID exactly as the table spells it. tbsp works, and tablespoon and Tbsp are validation errors.

Leave the unit out, or send null, for a plain count of the things themselves: 3 eggs, 4 apples. Use an item unit when you count something other than the thing: 2 cloves of garlic, 1 can of black beans, 3 rolls of paper towels.

The field names follow the app. A recipe ingredient has quantity, quantity_max for the top of a range, and unit. A shopping list item has quantity and unit. An inventory item has quantity and quantity_unit, and the size of one package as size_value and size_unit. Other fields called unit, such as the unit of a maintenance task's interval (day, week, month or year), are not from this list.

curl -X POST https://rigel.house/api/v1/households/hh_01JC8Q4W2N7XK5R3VYTZ9D6HBE/commands/recipes.ingredient.add \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cmd_01JC9A3M5N6P3VZ8KW1TXQ4DRG" \
  -d '{
    "recipe_id": "rcp_01JC9C1H8W3ZT6QXN5KDV2RMYA",
    "name": "garlic",
    "quantity": 2,
    "quantity_max": 3,
    "unit": "clove",
    "preparation": "minced"
  }'

See recipes.ingredient.add for the rest of that command, and IDs and formats for how amounts sit beside other values.

There are 31 units. Sizes are in grams for mass and milliliters for volume. Volume sizes are US customary, so a cup is 236.5882365 ml. A recipe written in metric cups is recorded in milliliters.

Mass converts to mass and volume converts to volume. Mass and volume don't convert to each other, because that depends on what is being measured: a cup of flour and a cup of honey weigh different amounts. An item unit converts only to itself, and a plain count converts to nothing.

To convert, multiply by the source unit's size, divide by the target's, and round to 6 decimal places. Rounding at 6 places gives the same result on every platform and no floating-point noise.

Rigel converts when it has to, such as when it adds two amounts of the same ingredient. The sum is in the first amount's unit, so 1 cup plus 2 tbsp is 1.125 cup, shown as 1⅛ cups. Amounts that don't convert stay separate.

Some queries return an amount already written for people, such as the amount on each ingredient from recipes.recipe.get. Use it as it is. If you format your own, follow these rules, which are the ones Rigel uses. Text is English only.

• Units with a short form are never pluralized: 2 tbsp, 2 lb.
• Units shown as words are plural unless the amount is exactly 1 or a fraction below 1: ½ cup, 1½ cups, 1 can, 3 cans.
• A range uses an en dash and is plural: 2–3 cloves.
• Metric amounts are decimals with at most 2 places and no trailing zeros: 1.5 kg, 0.25 L.
• Everything else uses a fraction when the amount is within 0.02 of an eighth or a third, and otherwise a decimal with at most 2 places.

A unit's ID is never renamed or removed, because stored rows and queued commands use it. New units are added when an app needs one. So a client should treat the list as open: if you read a unit ID you don't know, show the ID rather than failing, and don't copy this table into your code when you can read it from the reference. Every field that takes a unit lists the current IDs.