Difference between revisions of "API Fields"

From Open Food Facts wiki
Jump to navigation Jump to search
(formatting)
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
[[Category:API]]
 
== Data fields in the API ==
 
== Data fields in the API ==
 
This file describes the fields from the CSV and json export of the products in the Open Food Facts database.
 
This file describes the fields from the CSV and json export of the products in the Open Food Facts database.
  
See http://world.openfoodfacts.org/data for more information.
+
See https://world.openfoodfacts.org/data for more information.
  
The file encoding is Unicode UTF-8. The character that separates fields is <tab> (tabulation).
+
The file encoding is Unicode UTF-8.  
 +
=== CSV API ===
 +
The character that separates fields is <tab> (tabulation).
 +
=== JSON API ===
 +
==== Status 0 ====
 +
This status indicates that the product can not be found
 +
<nowiki>{ "status_verbose":"product not found",
 +
"status":0,
 +
"code":"32562641919" }</nowiki>
  
== Generalities ==
+
== Generalities ==
  
 
* fields that end with _t are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)
 
* fields that end with _t are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)
Line 15: Line 24:
  
 
== List of fields ==
 
== List of fields ==
 
+
See also [[Nutrients_handling_in_Open_Food_Facts|this page]].
 
=== general information ===
 
=== general information ===
  
Line 73: Line 82:
 
* ingredients_that_may_be_from_palm_oil
 
* ingredients_that_may_be_from_palm_oil
 
* ingredients_that_may_be_from_palm_oil_tags
 
* ingredients_that_may_be_from_palm_oil_tags
* nutrition_grade_fr : nutrition grade ('a' to 'e'). see http://fr.openfoodfacts.org/score-nutritionnel-experimental-france
+
* nutrition_grade_fr : nutrition grade ('a' to 'e'). see https://fr.openfoodfacts.org/score-nutritionnel-experimental-france
 
* main_category
 
* main_category
 
* main_category_fr
 
* main_category_fr
Line 80: Line 89:
  
 
=== nutrition facts ===
 
=== nutrition facts ===
 +
The nutrition facts are presented by multiple fields per nutrition fact. Each nutrition fact is presented by a key, i.e. "salt", "fat", etc. The fields can also be found in the taxonomy translation file.
 +
 +
The fields can have the following structure:
 +
* key_value (string)  - the standardized value of a serving of 100g (100ml) for type key (eg in json: "salt_100g":"0.19");
 +
* key_unit (string) - the units used in the other fields (eg in json: "carbohydrates_unit":"g"). Possible values are "kg", "g", "mg, "µg", "l", "ml", "%" or "";
 +
key_value and key_unit are what is entered by the user, or passed to the write api, with the "key" and "key_unit" fields.
 +
* key (string) - the value for the nutrition fact key (eg in json: "fiber":"0.5");
 +
Then "key" is a conversion in the default unit of the field (kJ or g)
 +
* key_serving (string) -  the value of a serving for type key (eg: in json "carbohydrates_serving":"5.82"). The size of the servig is found in the serving field;
 +
* key_100g (string) - the standardized value of a serving of 100g (100ml) for type key (eg in json: "salt_100g":"0.19");
 +
And "key_serving" "Key_100g" are values for the serving size or 100g. One of them is equal to "key", the other is converted.
 +
* key_label (string) - a more user friendly text explaining the
 +
 +
Only the nutrition facts that are actually found on the packaging are present in the interface.
  
energy_100g
+
The following nutrition keys are supported:
proteins_100g
+
* energy
casein_100g
+
* proteins
serum-proteins_100g
+
* casein
nucleotides_100g
+
* serum-proteins
carbohydrates_100g
+
* nucleotides
sugars_100g
+
* carbohydrates
sucrose_100g
+
* sugars
glucose_100g
+
* sucrose
fructose_100g
+
* glucose
lactose_100g
+
* fructose
maltose_100g
+
* lactose
maltodextrins_100g
+
* maltose
starch_100g
+
* maltodextrins
polyols_100g
+
* starch
fat_100g
+
* polyols
saturated-fat_100g
+
* fat
butyric-acid_100g
+
* saturated-fat
caproic-acid_100g
+
* butyric-acid
caprylic-acid_100g
+
* caproic-acid
capric-acid_100g
+
* caprylic-acid
lauric-acid_100g
+
* capric-acid
myristic-acid_100g
+
* lauric-acid
palmitic-acid_100g
+
* myristic-acid
stearic-acid_100g
+
* palmitic-acid
arachidic-acid_100g
+
* stearic-acid
behenic-acid_100g
+
* arachidic-acid
lignoceric-acid_100g
+
* behenic-acid
cerotic-acid_100g
+
* lignoceric-acid
montanic-acid_100g
+
* cerotic-acid
melissic-acid_100g
+
* montanic-acid
monounsaturated-fat_100g
+
* melissic-acid
polyunsaturated-fat_100g
+
* monounsaturated-fat
omega-3-fat_100g
+
* polyunsaturated-fat
alpha-linolenic-acid_100g
+
* omega-3-fat
eicosapentaenoic-acid_100g
+
* alpha-linolenic-acid
docosahexaenoic-acid_100g
+
* eicosapentaenoic-acid
omega-6-fat_100g
+
* docosahexaenoic-acid
linoleic-acid_100g
+
* omega-6-fat
arachidonic-acid_100g
+
* linoleic-acid
gamma-linolenic-acid_100g
+
* arachidonic-acid
dihomo-gamma-linolenic-acid_100g
+
* gamma-linolenic-acid
omega-9-fat_100g
+
* dihomo-gamma-linolenic-acid
oleic-acid_100g
+
* omega-9-fat
elaidic-acid_100g
+
* oleic-acid
gondoic-acid_100g
+
* elaidic-acid
mead-acid_100g
+
* gondoic-acid
erucic-acid_100g
+
* mead-acid
nervonic-acid_100g
+
* erucic-acid
trans-fat_100g
+
* nervonic-acid
cholesterol_100g
+
* trans-fat
fiber_100g
+
* cholesterol
sodium_100g
+
* fiber
alcohol_100g : % vol of alcohol
+
* sodium
vitamin-a_100g
+
* alcohol: % vol of alcohol
vitamin-d_100g
+
* vitamin-a
vitamin-e_100g
+
* vitamin-d
vitamin-k_100g
+
* vitamin-e
vitamin-c_100g
+
* vitamin-k
vitamin-b1_100g
+
* vitamin-c
vitamin-b2_100g
+
* vitamin-b1
vitamin-pp_100g
+
* vitamin-b2
vitamin-b6_100g
+
* vitamin-pp
vitamin-b9_100g
+
* vitamin-b6
vitamin-b12_100g
+
* vitamin-b9
biotin_100g
+
* vitamin-b12
pantothenic-acid_100g
+
* biotin
silica_100g
+
* pantothenic-acid
bicarbonate_100g
+
* silica
potassium_100g
+
* bicarbonate
chloride_100g
+
* potassium
calcium_100g
+
* chloride
phosphorus_100g
+
* calcium
iron_100g
+
* phosphorus
magnesium_100g
+
* iron
zinc_100g
+
* magnesium
copper_100g
+
* zinc
manganese_100g
+
* copper
fluoride_100g
+
* manganese
selenium_100g
+
* fluoride
chromium_100g
+
* selenium
molybdenum_100g
+
* chromium
iodine_100g
+
* molybdenum
caffeine_100g
+
* iodine
taurine_100g
+
* caffeine
ph_100g : pH (no unit)
+
* taurine
fruits-vegetables-nuts_100g : % of fruits, vegetables and nuts (excluding potatoes, yams, manioc)
 
  
carbon-footprint_100g : carbon footprint (indicated on some products)
+
==== Specific nutrition keys====
 +
* carbon-footprint_100g : carbon footprint (indicated on some products)
 +
* ph_100g : pH (no unit)
 +
* cocoa - minimal cacao content of the product in %. Note the TYPO.
 +
* fruits-vegetables-nuts_100g : % of fruits, vegetables and nuts (excluding potatoes, yams, manioc)
  
nutrition-score-fr_100g : experimental nutrition score derived from the UK FSA score and adapted for the French market (formula defined by the team of Professor Hercberg)
+
* nutrition-score-fr_100g : experimental nutrition score derived from the UK FSA score and adapted for the French market (formula defined by the team of Professor Hercberg)
nutrition-score-uk_100g : nutrition score defined by the UK Food Standards Administration (FSA)
+
* nutrition-score-uk_100g : nutrition score defined by the UK Food Standards Administration (FSA)

Latest revision as of 01:16, 30 March 2024

Data fields in the API

This file describes the fields from the CSV and json export of the products in the Open Food Facts database.

See https://world.openfoodfacts.org/data for more information.

The file encoding is Unicode UTF-8.

CSV API

The character that separates fields is <tab> (tabulation).

JSON API

Status 0

This status indicates that the product can not be found { "status_verbose":"product not found", "status":0, "code":"32562641919" }

Generalities

  • fields that end with _t are dates in the UNIX timestamp format (number of seconds since Jan 1st 1970)
  • fields that end with _datetime are dates in the iso8601 format: yyyy-mm-ddThh:mn:ssZ
  • fields that end with _tags are comma separated list of tags (e.g. categories_tags is the set of normalized tags computer from the categories field)
  • fields that end with a language 2 letter code (e.g. fr for French) is the set of tags in that language
  • fields that end with _100g correspond to the amount of a nutriment (in g) for 100 g or 100 ml of product

List of fields

See also this page.

general information

  • code : barcode of the product (can be EAN-13 or internal codes for some food stores), for products without a barcode, Open Food Facts assigns a number starting with the 200 reserved prefix
  • url : url of the product page on Open Food Facts
  • creator : contributor who first added the product
  • created_t : date that the product was added (UNIX timestamp format)
  • created_datetime : date that the product was added (iso8601 format: yyyy-mm-ddThh:mn:ssZ)
  • last_modified_t : date that the product page was last modified
  • last_modified_datetime
  • product_name : name of the product
  • generic_name
  • quantity : quantity and unit

tags

  • packaging : shape, material
  • packaging_tags
  • brands
  • brands_tags
  • categories
  • categories_tags
  • categories_fr
  • origins : origins of ingredients
  • origins_tags
  • manufacturing_places : places where manufactured or transformed
  • manufacturing_places_tags
  • labels
  • labels_tags
  • labels_fr
  • emb_codes
  • emb_codes_tags
  • first_packaging_code_geo : coordinates corresponding to the first packaging code indicated
  • cities
  • cities_tags
  • purchase_places
  • stores
  • countries : list of countries where the product is sold
  • countries_tags
  • countries_fr

ingredients

  • ingredients_text
  • traces
  • traces_tags

misc. data

  • serving_size : serving size in g (or ml)
  • no_nutriments : indicates if the nutrition facts are indicated on the food label
  • additives_n : number of food additives
  • additives
  • additives_tags
  • ingredients_from_palm_oil_n
  • ingredients_from_palm_oil
  • ingredients_from_palm_oil_tags
  • ingredients_that_may_be_from_palm_oil_n
  • ingredients_that_may_be_from_palm_oil
  • ingredients_that_may_be_from_palm_oil_tags
  • nutrition_grade_fr : nutrition grade ('a' to 'e'). see https://fr.openfoodfacts.org/score-nutritionnel-experimental-france
  • main_category
  • main_category_fr
  • image_url
  • image_small_url

nutrition facts

The nutrition facts are presented by multiple fields per nutrition fact. Each nutrition fact is presented by a key, i.e. "salt", "fat", etc. The fields can also be found in the taxonomy translation file.

The fields can have the following structure:

  • key_value (string) - the standardized value of a serving of 100g (100ml) for type key (eg in json: "salt_100g":"0.19");
  • key_unit (string) - the units used in the other fields (eg in json: "carbohydrates_unit":"g"). Possible values are "kg", "g", "mg, "µg", "l", "ml", "%" or "";

key_value and key_unit are what is entered by the user, or passed to the write api, with the "key" and "key_unit" fields.

  • key (string) - the value for the nutrition fact key (eg in json: "fiber":"0.5");

Then "key" is a conversion in the default unit of the field (kJ or g)

  • key_serving (string) - the value of a serving for type key (eg: in json "carbohydrates_serving":"5.82"). The size of the servig is found in the serving field;
  • key_100g (string) - the standardized value of a serving of 100g (100ml) for type key (eg in json: "salt_100g":"0.19");

And "key_serving" "Key_100g" are values for the serving size or 100g. One of them is equal to "key", the other is converted.

  • key_label (string) - a more user friendly text explaining the

Only the nutrition facts that are actually found on the packaging are present in the interface.

The following nutrition keys are supported:

  • energy
  • proteins
  • casein
  • serum-proteins
  • nucleotides
  • carbohydrates
  • sugars
  • sucrose
  • glucose
  • fructose
  • lactose
  • maltose
  • maltodextrins
  • starch
  • polyols
  • fat
  • saturated-fat
  • butyric-acid
  • caproic-acid
  • caprylic-acid
  • capric-acid
  • lauric-acid
  • myristic-acid
  • palmitic-acid
  • stearic-acid
  • arachidic-acid
  • behenic-acid
  • lignoceric-acid
  • cerotic-acid
  • montanic-acid
  • melissic-acid
  • monounsaturated-fat
  • polyunsaturated-fat
  • omega-3-fat
  • alpha-linolenic-acid
  • eicosapentaenoic-acid
  • docosahexaenoic-acid
  • omega-6-fat
  • linoleic-acid
  • arachidonic-acid
  • gamma-linolenic-acid
  • dihomo-gamma-linolenic-acid
  • omega-9-fat
  • oleic-acid
  • elaidic-acid
  • gondoic-acid
  • mead-acid
  • erucic-acid
  • nervonic-acid
  • trans-fat
  • cholesterol
  • fiber
  • sodium
  • alcohol: % vol of alcohol
  • vitamin-a
  • vitamin-d
  • vitamin-e
  • vitamin-k
  • vitamin-c
  • vitamin-b1
  • vitamin-b2
  • vitamin-pp
  • vitamin-b6
  • vitamin-b9
  • vitamin-b12
  • biotin
  • pantothenic-acid
  • silica
  • bicarbonate
  • potassium
  • chloride
  • calcium
  • phosphorus
  • iron
  • magnesium
  • zinc
  • copper
  • manganese
  • fluoride
  • selenium
  • chromium
  • molybdenum
  • iodine
  • caffeine
  • taurine

Specific nutrition keys

  • carbon-footprint_100g : carbon footprint (indicated on some products)
  • ph_100g : pH (no unit)
  • cocoa - minimal cacao content of the product in %. Note the TYPO.
  • fruits-vegetables-nuts_100g : % of fruits, vegetables and nuts (excluding potatoes, yams, manioc)
  • nutrition-score-fr_100g : experimental nutrition score derived from the UK FSA score and adapted for the French market (formula defined by the team of Professor Hercberg)
  • nutrition-score-uk_100g : nutrition score defined by the UK Food Standards Administration (FSA)