API Fields

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 http://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

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

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 http://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)