Nutrients

Every nutrition result reports the same 53 nutrients, keyed by stable public keys. The dictionary below is generated from the published contract (opis.public-nutrients/v1) and is also served at GET /v1/nutrients.

How values work

Portion totals. A nutrient value on an item is the amount in that item's portion — at its grams — not per 100 g. If you need per-100 g values (for example to rescale on the device), request them with ?include=per_100g and they appear beside the totals.

"nutrients": {
  "energy_kcal": { "value": 297.7, "unit": "kcal", "derivation": "analysed" },
  "vitamin_d": null
}

Null means "not measured", never zero. When the source database has no value for a nutrient, the value is null. Do not render it as 0 — show "not available" or leave it out. Most foods have complete macronutrients; vitamins and trace minerals are sparser, especially for fallback sources.

Meal totals skip nulls and tell you so. nutrition.totals.nutrients sums only the item values that exist, and nutrition.totals.completeness tells you, per nutrient, the share of resolved items that contributed (from 0 to 1). A vitamin D total with completeness 0.5 means half the items had no vitamin D value — the true total is probably higher. A nutrient that no item has is null in totals.

"totals": {
  "nutrients": { "energy_kcal": { "value": 341.2, "unit": "kcal" }, "vitamin_d": { "value": 0.4, "unit": "ug" } },
  "completeness": { "energy_kcal": 1.0, "vitamin_d": 0.5 },
  "items_unresolved": 0
}

Units are UCUM codes: g, mg, ug (micrograms, µg), kcal, kJ. A key's unit never changes within v1.

Provenance. Each value carries derivation — how the source database obtained it:

and each item's match says which database and food the values come from:

match.approximate: true marks a generic stand-in for a more specific food (for example a branded ready meal matched to its generic recipe).

Stability. Keys are append-only within v1: a key is never renamed or removed, and new nutrients may be added. Ignore keys you do not know.

Dictionary

The Sources column lists the databases that can supply each nutrient today. USDA fallbacks cover a subset of the dictionary; values a source cannot supply are null.