openfoodfacts-guide

Scope

Packaged, barcoded foods as Open Food Facts contributors recorded them: label text, declared allergens and traces, additives, Open Food Facts' computed grades, and nutrition per 100 g (per 100 ml for liquids) and per serving. It is not a verdict on whether a food is safe for a particular person, and it holds no recalls. Reference composition for generic, unbranded foods belongs to a food-composition database such as USDA FoodData Central.

Identifiers

Gates

1. Allergy questions: never answer "safe" or "free of X". Report what the record says and how far it goes. Read all three sources: ingredients_text (in the label's own language, often with allergens emphasized in capitals or brackets), allergens_tags, and traces_tags. An empty traces_tags means no trace data was entered, not that the label carries no warning. When the three disagree, say the record is unreliable: a record can carry a truncated ingredients text beside allergen tags that text cannot support. End by pointing the user to the physical label.
2. Nut allergies need two tags. en:nuts means tree nuts; peanuts are the separate en:peanuts. Check both on the record, and pass both to exclude_allergens or exclude_traces.
3. Free-from searches start from a positive claim. An exclusion alone also passes every product with no allergen data entered, so select first on something the record asserts: a label (en:no-gluten, en:vegan) or a free-from category (en:gluten-free-pasta). Add the exclusion on top, then confirm shortlisted barcodes with off_get_product. For vegan, the ingredients-analysis verdict en:vegan is Open Food Facts' computation from the parsed ingredients, while the label en:vegan is a claim printed on the pack. They are different evidence, so say which one you used.
4. Grade ranges take one call per grade. nutrition_grade and nova_group each take a single value. For "Nutri-Score B or better", search once with a and once with b, then merge the results. A product with no grade drops out of both searches.
5. A product named without a barcode: pick a barcode deliberately. Don't take the first search row on faith. Records for one product can carry different Nutri-Score and NOVA grades even when their nutrition is identical, when one record's ingredient list or other entered data is incomplete. Prefer the user's own barcode. Otherwise sort by unique_scans_n, favor high completeness, and name the barcode the answer came from.
6. Grades are Open Food Facts' computation from the record, not the grade printed on the pack. When a user quotes a different grade, the record's data is the first suspect: check its completeness, data_quality_tags, and ingredient list.
7. Spend searches one at a time. The search budget is about 10 upstream requests a minute on the default configuration. The server process holds it, so every caller of a shared deployment draws from it, and each retry of a failing request spends its own slot. Never fan out parallel searches; when the budget runs out, the error's data.retryAfter gives the wait. Product lookups draw on a separate budget, but off_compare_products spends one lookup from it per barcode, the same as off_get_product.