View source for 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.

== Why it's more complex that you might think ==

* 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

== How it works ==

=== Data input ===

==== Fields sent by the write API ====

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)

=== Data display ===

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:
* indicate if the nutrition facts are per 100g or per serving.
* convert the value in g or in kJ to the desired unit.

=== Data edit ===

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) simpler ==

* In the API, rename the "nutrient-id" fields (such as energy-kj, saturated-fat) to "nutrient-id_value", so that it matches the name of the field stored.
* Store the energy-kcal values in kcal, without converting them to kJ
** This is probably what people intuitively expect
** It removes unnecessary conversions from kcal to kJ and back (which is not trivial, as some people/apps may choose a different conversion factor, such as 4.2 or 4.185)
** This would be a breaking change if some apps use the energy-kcal_100g/serving or energy-kj_100g/serving fields