Difference between revisions of "API Fields"
Jump to navigation
Jump to search
(Created page) |
|||
| (15 intermediate revisions by 4 users not shown) | |||
| Line 1: | Line 1: | ||
| + | [[Category:API]] | ||
| + | [[Category:Fields]] | ||
== 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 | + | 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 _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 == | == 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 | ||
| − | + | === 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 | |
| − | serum- | + | * casein |
| − | + | * serum-proteins | |
| − | + | * nucleotides | |
| − | + | * carbohydrates | |
| − | + | * sugars | |
| − | + | * sucrose | |
| − | + | * glucose | |
| − | + | * fructose | |
| − | + | * lactose | |
| − | + | * maltose | |
| − | + | * maltodextrins | |
| − | + | * starch | |
| − | + | * polyols | |
| − | saturated- | + | * fat |
| − | butyric- | + | * saturated-fat |
| − | caproic- | + | * butyric-acid |
| − | caprylic- | + | * caproic-acid |
| − | capric- | + | * caprylic-acid |
| − | lauric- | + | * capric-acid |
| − | myristic- | + | * lauric-acid |
| − | palmitic- | + | * myristic-acid |
| − | stearic- | + | * palmitic-acid |
| − | arachidic- | + | * stearic-acid |
| − | behenic- | + | * arachidic-acid |
| − | lignoceric- | + | * behenic-acid |
| − | cerotic- | + | * lignoceric-acid |
| − | montanic- | + | * cerotic-acid |
| − | melissic- | + | * montanic-acid |
| − | monounsaturated- | + | * melissic-acid |
| − | polyunsaturated- | + | * monounsaturated-fat |
| − | omega-3- | + | * polyunsaturated-fat |
| − | alpha-linolenic- | + | * omega-3-fat |
| − | eicosapentaenoic- | + | * alpha-linolenic-acid |
| − | docosahexaenoic- | + | * eicosapentaenoic-acid |
| − | omega-6- | + | * docosahexaenoic-acid |
| − | linoleic- | + | * omega-6-fat |
| − | arachidonic- | + | * linoleic-acid |
| − | gamma-linolenic- | + | * arachidonic-acid |
| − | dihomo-gamma-linolenic- | + | * gamma-linolenic-acid |
| − | omega-9- | + | * dihomo-gamma-linolenic-acid |
| − | oleic- | + | * omega-9-fat |
| − | elaidic- | + | * oleic-acid |
| − | gondoic- | + | * elaidic-acid |
| − | mead- | + | * gondoic-acid |
| − | erucic- | + | * mead-acid |
| − | nervonic- | + | * erucic-acid |
| − | trans- | + | * nervonic-acid |
| − | + | * trans-fat | |
| − | + | * cholesterol | |
| − | + | * fiber | |
| − | + | * sodium | |
| − | vitamin- | + | * alcohol: % vol of alcohol |
| − | vitamin- | + | * vitamin-a |
| − | vitamin- | + | * vitamin-d |
| − | vitamin- | + | * vitamin-e |
| − | vitamin- | + | * vitamin-k |
| − | vitamin- | + | * vitamin-c |
| − | vitamin- | + | * vitamin-b1 |
| − | vitamin- | + | * vitamin-b2 |
| − | vitamin- | + | * vitamin-pp |
| − | vitamin- | + | * vitamin-b6 |
| − | vitamin- | + | * vitamin-b9 |
| − | + | * vitamin-b12 | |
| − | pantothenic- | + | * biotin |
| − | + | * pantothenic-acid | |
| − | + | * silica | |
| − | + | * bicarbonate | |
| − | + | * potassium | |
| − | + | * chloride | |
| − | + | * calcium | |
| − | + | * phosphorus | |
| − | + | * iron | |
| − | + | * magnesium | |
| − | + | * zinc | |
| − | + | * copper | |
| − | + | * manganese | |
| − | + | * fluoride | |
| − | + | * selenium | |
| − | + | * chromium | |
| − | + | * molybdenum | |
| − | + | * iodine | |
| − | + | * caffeine | |
| − | + | * taurine | |
| − | |||
| − | 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 10:20, 6 August 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)