API Fields

From Open Food Facts wiki
Revision as of 09:46, 24 April 2016 by Aleene (talk | contribs) (Added some explanation)
Jump to navigation Jump to search

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. The character that separates fields is <tab> (tabulation).

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

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 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 (string) - the value for the nutrition type key (eg in json: "fiber":"0.5");
  • 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_value (string) - the standardized value of a serving of 100g (100ml) for type key (eg in json: "salt_100g":"0.19");
  • key_100g (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 "";

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)
  • 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)