| name | openfoodfacts-product-lookup |
| description | Look up food products by barcode or search with filters. Find products by category, nutrition grade, eco-score, label, ingredient, or allergen. Use when you have a barcode or need to find products matching specific criteria. |
| compatibility | Requires openfoodfacts binary installed (see openfoodfacts-shared skill). |
openfoodfacts-product-lookup
Workflow for finding food product data from the Open Food Facts database.
Look Up a Product by Barcode
openfoodfacts --json products get <barcode>
Example (Nutella):
openfoodfacts --json products get 3017624010701
Use --fields to return only what you need:
openfoodfacts --json --fields product_name,brands,nutriscore_grade,ecoscore_grade,ingredients_text_en products get 3017624010701
If the product is not found, the CLI exits 1 with {"error": "product not found: <barcode>"}.
Search by Filters
Filter-only search (no full-text query) uses the v2 API:
openfoodfacts --json products search --category en:chocolates --nutrition-grade a
Available filter flags:
| Flag | Description | Example |
|---|
--category <tag> | Category tag | en:chocolates |
--nutrition-grade <a-e> | Nutri-Score | a |
--ecoscore-grade <a-e> | Eco-Score | b |
--label <tag> | Label tag | en:organic |
--ingredient <tag> | Ingredient tag | en:salt |
--allergen <tag> | Allergen tag | en:gluten |
Combine filters freely โ all are ANDed:
openfoodfacts --json products search --category en:biscuits-and-cakes --nutrition-grade a --label en:organic
Full-Text Search
Use --query for keyword search (routes to the v1 search endpoint):
openfoodfacts --json products search --query "organic olive oil"
Combine with filters:
openfoodfacts --json products search --query "dark chocolate" --nutrition-grade b --label en:fair-trade
Pagination
Default: 20 results per page. The response envelope tells you how many pages exist:
{"count": 4821, "page": 1, "page_count": 242, "page_size": 20, "products": [...]}
Fetch a specific page:
openfoodfacts --json products search --category en:chocolates --page 3 --page-size 50
Fetch all pages at once (returns flat array โ use with care on large result sets):
openfoodfacts --json products search --category en:chocolates --nutrition-grade a --all
Tips
- Tag values are always prefixed with a language code:
en:chocolates, not chocolates. Use facets list to discover valid tags.
- Use
--fields code,product_name,nutriscore_grade on search results to keep response sizes small.
--all can trigger many API calls. Check page_count in a regular search first.- Rate limit for search is 10 req/min โ avoid tight loops.
