API Fields

From Open Food Facts wiki
Revision as of 13:43, 11 December 2019 by Aleene (talk | contribs) (Added @stephane's clarifications)
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.

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

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