Food Database API

What one request does

GET /v1/foods/{id} takes the UUID you got from a search or a barcode lookup and returns the whole normalized record. There is no field selection and no pagination: the record for 62ea12b8-b260-c288-5c38-3a4906f5d6dd (barcode 5449000000996, source openfoodfacts) comes back with every key in the 200 schema, and anything the source lacks is null rather than omitted.

Authenticate with the X-API-Key header. The only optional input is ?lang=, one of en, fr, es, de, it or bg. It appends category_localized, category_segments_localized and allergens_localized and leaves every other key untouched, so adding lang later never breaks an existing parser. Every response also carries an X-Request-Id header to quote in support requests.

Names, ingredients and the main entry

name and ingredients are arrays of {lang, text}. The first entry has lang main and mirrors name_default and ingredients_default; product_lang tells you which real language that is. On the Coca-Cola record the main name is Original Taste, the fr entry reads Coca-Cola en canette and the bg entry reads Кока-Кола. Pick the entry matching your UI language and fall back to name_default.

Expect ingredients to be longer than the number of languages: Open Food Facts stores ingredient text per packaging variant, so the same lang can appear more than once on a record, often with identical text, as it does here. Deduplicate on lang and keep the first occurrence. The text is contributor-entered and returned as-is; the ar entry here contains label fragments that are not ingredients, so validate before parsing it into structures.

Category, tags, allergens and lang

category is one comma-joined string from broad to narrow: Beverages and beverages preparations,Beverages,Carbonated drinks,Sodas,Colas,pt:bebidas cafeína. Split on the comma; the last level is the most specific. categories_tags holds the same levels as machine tags (en:beverages, en:carbonated-drinks, en:colas) and is the stable value to filter or group on, because the display string changes when contributors edit the product.

allergens and traces use the same en:milk style tags, as do countries (en:albania, en:austria, en:belgium) and labels. null means the source stated nothing, not that the product is allergen-free; this record has allergens: null and traces: null, so an allergy warning should read unknown, not none.

With ?lang=bg the API adds category_localized as one translated string, category_segments_localized with one entry per hierarchy level, and allergens_localized parallel to allergens. A level or tag without a dictionary entry is null inside the array, so keep the index aligned with categories_tags or allergens and fall back to the English tag for null slots.

Scores, serving size and summary nutrients

nutriscore is a lowercase letter (e here), nova_group a number (4) and ecoscore_grade a string that can be a letter or a sentinel such as not-applicable, which is what this beverage returns. Treat all three as nullable and do not map not-applicable to a color band.

serving_size_raw and quantity are free text copied from the label. serving_size_raw reads 1 can (330 ml) and is fine for display; quantity reads 0kg on this record, a contributor error, so never compute pack weight from it without a sanity check.

nutrition_summary gives six per-100 g values: energy_kcal, proteins_g, carbs_g, fat_g, sugars_g and fiber_g. Each can be null on its own and the object can be null when the source has no nutrition panel. It covers a list row or a quick comparison; the full 40+ nutrients live on the Nutrition API at /v1/foods/{id}/nutrients with the same id.

Stable ids, caching and the usual flow

The id is deterministic, derived from the source and the source's own product id, so the same product gets the same UUID on every re-import. Store ids in your own tables and re-fetch months later without a remapping step. barcode is nullable in the schema, so prefer the id over the barcode as your join key.

A 200 carries Cache-Control: public, max-age=300 and a 404 carries max-age=60, so a CDN or HTTP cache in front of your service honors them without configuration. If you cache in your own database, key on id plus lang, since the localized keys differ per language.

The usual flow: obtain an id from the Food Search API or the Barcode Lookup API, store it, and call this endpoint when a detail view needs the full record. To refresh many stored ids at once, the Bulk Food Lookup API takes a list in one request on Starter and above. Images are Open Food Facts contributor photos hosted at images.openfoodfacts.org and records from other sources may have none, so render a placeholder whenever image_url is null.