Difference between revisions of "API Fields"

From Open Food Facts wiki
Jump to navigation Jump to search
(Created page)
 
 
(14 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)
- fields that end with _datetime are dates in the iso8601 format: yyyy-mm-ddThh:mn:ssZ
+
* 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 _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 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
+
* 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 ==
 
== List of fields ==
 
+
See also [[Nutrients_handling_in_Open_Food_Facts|this page]].
 
=== general information ===
 
=== 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
+
* 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
+
* url : url of the product page on Open Food Facts
creator : contributor who first added the product
+
* creator : contributor who first added the product
created_t : date that the product was added (UNIX timestamp format)
+
* 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)
+
* 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_t : date that the product page was last modified
last_modified_datetime
+
* last_modified_datetime
product_name : name of the product
+
* product_name : name of the product
generic_name
+
* generic_name
quantity : quantity and unit
+
* quantity : quantity and unit
  
 
=== tags ===
 
=== tags ===
  
packaging : shape, material
+
* packaging : shape, material
packaging_tags
+
* packaging_tags
brands
+
* brands
brands_tags
+
* brands_tags
categories
+
* categories
categories_tags
+
* categories_tags
categories_fr
+
* categories_fr
origins : origins of ingredients
+
* origins : origins of ingredients
origins_tags
+
* origins_tags
manufacturing_places : places where manufactured or transformed
+
* manufacturing_places : places where manufactured or transformed
manufacturing_places_tags
+
* manufacturing_places_tags
labels
+
* labels
labels_tags
+
* labels_tags
labels_fr
+
* labels_fr
emb_codes
+
* emb_codes
emb_codes_tags
+
* emb_codes_tags
first_packaging_code_geo : coordinates corresponding to the first packaging code indicated
+
* first_packaging_code_geo : coordinates corresponding to the first packaging code indicated
cities
+
* cities
cities_tags
+
* cities_tags
purchase_places
+
* purchase_places
stores
+
* stores
countries : list of countries where the product is sold
+
* countries : list of countries where the product is sold
countries_tags
+
* countries_tags
countries_fr
+
* countries_fr
  
 
=== ingredients ===
 
=== ingredients ===
 +
* ingredients_text
 +
* traces
 +
* traces_tags
  
ingredients_text
+
=== misc. data ===
traces
+
* serving_size : serving size in g (or ml)
traces_tags
+
* 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
  
=== misc. data ===
+
=== 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.
  
serving_size : serving size in g
+
The fields can have the following structure:
no_nutriments : indicates if the nutrition facts are indicated on the food label
+
* key_value (string)  - the standardized value of a serving of 100g (100ml) for type key (eg in json: "salt_100g":"0.19");
additives_n : number of food additives
+
* 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 "";
additives
+
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.
additives_tags
+
* key (string) - the value for the nutrition fact key (eg in json: "fiber":"0.5");
ingredients_from_palm_oil_n
+
Then "key" is a conversion in the default unit of the field (kJ or g)
ingredients_from_palm_oil
+
* 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;
ingredients_from_palm_oil_tags
+
* key_100g (string) - the standardized value of a serving of 100g (100ml) for type key (eg in json: "salt_100g":"0.19");
ingredients_that_may_be_from_palm_oil_n
+
And "key_serving" "Key_100g" are values for the serving size or 100g. One of them is equal to "key", the other is converted.
ingredients_that_may_be_from_palm_oil
+
* key_label (string) - a more user friendly text explaining the
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
 
main_category
 
main_category_fr
 
image_url
 
image_small_url
 
  
=== nutrition facts ===
+
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)