Nutrients handling in Open Food Facts

Summary

This page describes how nutrients are stored in Open Food Facts and how they can be read or written through the API.

Nutrients lists are different depending on countries
Nutrients list are different depending on time (evolutions in the law)
- e.g. in 2013 in Europe, the main unit for energy became kJ instead of kcal, and salt replaced sodium, with salt = 2.5 x sodium
Nutrients on labels may be in different units
- e.g. sodium could be listed in mg or in g
- US uses calories (kcal), EU uses kJ + kcal
Nutrients may be specified per 100g, per 100ml (which may be different than per 100g), per serving, or both
Nutrients may be specified for the product sold as-is, or prepared (with water, milk or something else), or both
Some apps, producers, databases etc. may give us values in a specific unit which is not the one that is on the label

Apps (+ the OFF web site edit form) send:

nutrition_data_per : "100g" or "serving"
serving_size (optional, but very useful, in particular if the nutrition facts are specified per serving)
for each nutrient:
- nutrient-id (e.g. saturated-fat, energy-kcal) : value for the nutrient, for the size specified in "nutrition_data_per"
- nutrient-id_unit (e.g. saturated-fat_unit, energy-kcal_unit) : the unit of the value passed (e.g. "g", "mg", "kcal", "kJ")

Notes about the energy fields:

Energy on labels can be written in kcal, kJ or both
when the energy is written in both, there is no simple conversion ratio between kcal and kJ
- This is because labelling laws in EU, US, CA etc. specify that the energy fields can (or must) be computed by multiplying and summing values for carbohydrates, proteins, fat etc.
- see https://esha.com/calorie-calculation-country/ for details
energy-kj and energy-kcal are the identifiers (nutrient-id) of the "Energy in kJ" and "Energy in kcal" fields.
old apps used to pass energy (as we had only one energy field instead of energy-kcal + energy-kj)
- for those apps, the energy_unit field is used to populate the corresponding energy-kj or energy-kcal field

==== Fields stored and computed by Product Opener

nutrient-id_value : what was passed in the nutrient-id field
nutrient-id_unit : what was passed in the nutrient-id_unit field
nutrient-id : the value converted in the default unit (currently kJ for all energy fields, including energy-kcal)
nutrient-id_[value of nutrition_data_per) is set to nutrient-id (e.g. if nutrition_data_per is "100g", the value of sugars_100g is set to the value of sugars
if the serving size is known, we compute the value for the other field (nutrient-id_100g or nutrient-id_serving)

The OFF web site, and apps, should use those fields to display the nutrition facts:

nutrient-id_100g or nutrient-id_serving (depending on the value of nutrition_data_per) : value in g or in kJ

The web site and apps must:

The web site and apps that allow editing the nutrition facts must populate the table with the same rules than for data display.

=== Possible improvements to make thing (a bit)