Setup & Usage
grocy-barcode-size fills in the package size on your Grocy barcodes — but only when it's sure. This page covers setup and how it behaves.
How it works
- Every interval it finds Grocy barcodes with no size set.
- It looks each up in OpenFoodFacts and USDA FoodData Central.
- It writes a size only when both sources answer and agree (within ~10%, after converting to a common base). Otherwise the barcode is left blank and cached as "no data" so it isn't re-queried.
- When it writes, it sets the barcode's
amount+ unit, and — for freshly-scanned products still on the default unit with 0 stock — the product's stock unit too, so a 12 oz and an 18 oz box of the same thing are directly comparable.
Coverage: national brands fill reasonably; store brands (ALDI, Great Value…) usually have no data anywhere → one-time manual entry in Product → Barcodes (Grocy then remembers it forever).
Requirements
- A running Grocy instance + API key.
- Internet access to OpenFoodFacts + USDA FoodData Central.
- Python 3 with
requests.
Configuration (environment variables)
| Var | What it is | Default |
|---|---|---|
GROCY_URL / GROCY_KEY |
Grocy server URL + API key | — |
FDC_API_KEY |
USDA FoodData Central key | DEMO_KEY (rate-limited) |
INTERVAL |
Seconds between sweeps | 600 |
CACHE_FILE |
"No data" cache path | /app/cache.json |
DRY_RUN |
1 = log only, write nothing |
0 |
Get a free USDA key (recommended)
DEMO_KEY is heavily rate-limited (~30/hour). Grab a free key at https://fdc.nal.usda.gov/api-key-signup.html (instant, emailed) and set FDC_API_KEY.
OpenFoodFacts note
OFF requires an identifying User-Agent (and a default python-requests UA is Cloudflare-blocked). The code sets one — keep it set if you fork.
Deploy
enrich.py runs as a small daemon (loops every INTERVAL). A python:3.12-slim container with the script mounted and pip install requests on start is all it needs.
Using it
- Just scan products into Grocy as usual. When you scan something new, this fills its barcode size automatically if both databases confirm it.
- Items it can't confirm stay blank — set the size once in Product → Barcodes and Grocy keeps it.
- It only ever adds a size to a blank barcode; it won't overwrite sizes you've set.
Gotchas
- Grocy barcode size is a stored default. Editing the amount on the purchase screen is per-transaction and does not save back to the barcode — the persistent size is set in Product → Barcodes (or by this service). That's exactly why this tool refuses to write uncertain values.
- Store brands are the weak spot — neither database tends to have them. That's expected; manual-once is the fallback.
- Sources can disagree (e.g. a multipack vs. a single can) — when they do, it skips, on purpose.