1,083
edits
Changes
Jump to navigation
Jump to search
Nutrients handling in Open Food Facts (view source)
Revision as of 18:27, 1 June 2020
, 18:27, 1 June 2020Created page with "== 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 th..."
== 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.
=== Data output ===
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.
=== Data output ===