API/Read/Product
<Back to API/Read(Required reading)
Reading a product
The requested subdomain will be the locale fetched. (fr.openfoodfacts will fetch FR, world.openfoodfacts EN, world-fr FR products from the whole world)
Structure of the call
- https://world.openfoodfacts.org/api/v0/product/737628064502.xml
- https://world.openfoodfacts.org/api/v0/product/737628064502.json
The final number must be a valid barcode.
Status codes
If a product is not found
{ "status_verbose":"product not found", "code":"32421", "status":0 }
If the product is found properly
See a full example: API/Full JSON example
Fields within a product
Name
- product_name : name of the product : Coca Cola
- generic_name : name that shouldn't contain brands : Cola soda
- generic_name_LANG_CODE : name that shouldn't contain brands:
- generic_name_fr:soda au cola
- generic_name_en:cola soda
Barcodes
- 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
List of List of barcodes beginning with a given number
List of barcodes beginning with 3596710
- https://world.openfoodfacts.org/code/3596710xxxxxx.json
- https://world.openfoodfacts.org/code/3596710xxxxxx.xml
Quantity and unit
- quantity : quantity and unit
URL of the product page
- url : url of the product page on Open Food Facts
Brands
- brands
- brands_tags
List of Brands
Individual Brand
- https://world.openfoodfacts.org/brand/monoprix.json
- https://world.openfoodfacts.org/brand/monoprix.xml
Product images
- Images ensure the reliability of Open Food Facts data. It provides a primary source and proof of all the structured data. You may therefore want to display it along the structured information.
- We encourage you to let your users upload images for products that don't exist yet, and for existing products as well (packaging and information changes over time).
- We have different scales of images. Use them wisely to save bandwidth, both for your users and Open Food Facts.
Raw images
- image_small_url
- image_thumb_url
- image_url
Front image
- "image_front_url"
- "image_front_small_url"
- "image_front_thumb_url"
Ingredients image
- "image_ingredients_url"
- "image_ingredients_small_url"
- "image_ingredients_thumb_url"
Nutrition image
- "image_nutrition_url"
- "image_nutrition_small_url"
- "image_nutrition_thumb_url"
Languages
Languages on the packaging of the product.
List of languages present on packaging
List of products with given language on packaging
- https://world.openfoodfacts.org/language/italian.json
- https://world.openfoodfacts.org/language/italian.xml
List of products in Italian and Chinese
List of multilingual products
- https://world.openfoodfacts.org/language/multilingual.json
- https://world.openfoodfacts.org/language/multilingual.xml
List of products by language count
- https://world.openfoodfacts.org/language/1.json
- https://world.openfoodfacts.org/language/1.xml
- https://world.openfoodfacts.org/language/2.json
- https://world.openfoodfacts.org/language/2.xml
- https://world.openfoodfacts.org/language/3.json
- https://world.openfoodfacts.org/language/3.xml
Getting suggestions for languages
Labels
Labels
- labels
- labels_fr
Label tags
- labels_tags
- labels_debug_tags
- labels_prev_tags
- labels_next_tags
Label hierarchy
- labels_hierarchy
- labels_prev_hierarchy
- labels,labels_next_hierarchy
For a list of all taxonomized values in all supported languages, please refer to the Global labels taxonomy
List of labels
Individual label
- https://world.openfoodfacts.org/label/utz-certified.json
- https://world.openfoodfacts.org/label/utz-certified.xml
Label images
No format API is currently available. However, they are predictable:
https://static.openfoodfacts.org/images/lang/en/labels/eu-organic.135x90.svg
A full list is available at:
https://github.com/openfoodfacts/openfoodfacts-server/tree/master/html/images/lang/fr/labels https://github.com/openfoodfacts/openfoodfacts-server/tree/master/html/images/lang/en/labels https://github.com/openfoodfacts/openfoodfacts-server/tree/master/html/images/lang/de/labels
Getting suggestions for labels
Categories
For a list of all possible values in all supported languages, please refer to the Global categories taxonomy
- categories
- categories_tags
- categories_fr
- main_category
- main_category_fr
Hierarchy
The categories_hierarchy is sorted by the "level" of each category. Level 0 means the category has no children, level 1 means it has children that do not have other children, level 2 is when it has children that have children that do not have children etc.
List of categories
Individual category
- https://world.openfoodfacts.org/category/baby-foods.json
- https://world.openfoodfacts.org/category/baby-foods.xml
Getting suggestions for categories
Location of a product (from country to store)
Origins of ingredients
- origins : origins of ingredients
- origins_tags
Manufacturing Places
- manufacturing_places : places where manufactured or transformed
- manufacturing_places_tags
Cities
- cities
- cities_tags
Country of products
- countries : list of countries where the product is sold
- countries_tags
- countries_fr
List of Countries
Individual Country
- https://world.openfoodfacts.org/country/france.json
- https://world.openfoodfacts.org/country/france.xml
Getting suggestions for Countries
Purchase place of products
- purchase_places
List of purchase places
- https://world.openfoodfacts.org/purchase-places.json
- https://world.openfoodfacts.org/purchase-places.xml
Individual purchase place
- https://world.openfoodfacts.org/purchase-place/marseille-5.json
- https://world.openfoodfacts.org/purchase-place/marseille-5.xml
Store of products
- stores
List of Stores
Individual Store
- https://world.openfoodfacts.org/store/super-u.json
- https://world.openfoodfacts.org/store/super-u.xml
Composition of a product : ingredients, detected ingredients, traces, allergens
Ingredients
Do not make the assumption that the ingredient is or is not present based on this. Parsing errors happen.
List of ingredients on a specific product
- On a product ingredients_text contains the text of the ingredients.
- ingredients_text_fr, ingredients_text_nl… (the package of a product may be multilingual)
- ingredients_text_with_allergens_fr (same with HTML markup around allergens)
- This list is parsed and we construct an ingredients and ingredients_tags list, but those will contain synonyms etc. We do not have a full taxonomy for ingredients yet. It's a work in progress.
- ingredients
- percent: possible detected percentage (still unreliable)
- rank: the order of the ingredient in the ingredient list
- id: a slug version of the detected ingredient
- text: the raw text of the detected ingredient
- ingredients_tags
- ingredients
- The ingredients are not yet taxonomized on Open Food Facts. They are taxonomized on Open Beauty Facts
- The taxonomies of ingredients need expansion: Global ingredients taxonomy (OFF), Global ingredients taxonomy Open Beauty Facts
List of detected ingredients
List of products where a specific ingredient has been detected
- https://world.openfoodfacts.org/ingredient/sucre.xml
- https://world.openfoodfacts.org/ingredient/sucre.json
Getting suggestions for ingredients (ONLY FOR OBF at the moment)
Vitamins and minerals detection
Vitamins
"vitamins_tags":["en:vitamin-a","en:cholecalciferol","en:vitamin-e","en:vitamin-c","en:thiamin","en:riboflavin","en:niacin","en:vitamin-b6","en:folic-acid","en:vitamin-b12","en:biotin","en:phylloquinone"]
Minerals
"minerals_tags":["en:calcium-citrate","en:potassium-citrate","en:sodium-citrate","en:magnesium-chloride","en:calcium-phosphate","en:potassium-phosphate","en:ferrous-sulphate","en:zinc-sulphate","en:cupric-sulphate","en:manganese-sulphate","en:sodium-carbonate","en:potassium-iodide"]
Amino acids
"amino_acids_tags":["en:l-tryptophan"]
= Other nutritional substances
"other_nutritional_substances_tags":["en:taurine","en:inositol","en:choline-citrate","en:taurine","en:inositol","en:choline-citrate","en:taurine","en:inositol","en:choline-citrate"]<pre> ===== Palm Oil Detection ===== * 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 ====== Ingredients from palm oil ====== ======= List of ingredients from palm oil ======= * https://world.openfoodfacts.org/ingredients-from-palm-oil.json * https://world.openfoodfacts.org/ingredients-from-palm-oil.xml ======= List of products where a specific ingredient from palm oil has been detected ======= * https://world.openfoodfacts.org/ingredients-from-palm-oil/huile-de-palme.json * https://world.openfoodfacts.org/ingredients-from-palm-oil/huile-de-palme.xml ====== Ingredients that may be from palm oil ====== ======= List of ingredients that may be from palm oil ======= * https://world.openfoodfacts.org/ingredients-that-may-be-from-palm-oil.json * https://world.openfoodfacts.org/ingredients-that-may-be-from-palm-oil.xml ======= List of products where a specific ingredient that may be from palm oil has been detected ======= * https://world.openfoodfacts.org/ingredients-that-may-be-from-palm-oil/e470b-stearate-de-magnesium.json * https://world.openfoodfacts.org/ingredients-that-may-be-from-palm-oil/e470b-stearate-de-magnesium.xml =====Trace of products===== * traces * traces_tags ======List of Traces ====== * https://world.openfoodfacts.org/traces.json * https://world.openfoodfacts.org/traces.xml ======Individual Trace ====== * https://world.openfoodfacts.org/trace/eggs.json * https://world.openfoodfacts.org/trace/eggs.xml ======Getting suggestions for traces ====== * https://world.openfoodfacts.org/cgi/suggest.pl?lc=fr&tagtype=traces&string=m ===== Food (or cosmetic) additives ===== * additives_n : number of food additives * additives * additives_tags For a list of all taxonomized values in all supported languages, please refer to the [[Global additives taxonomy]] ====== List of Additives ====== * https://world.openfoodfacts.org/additives.json * https://world.openfoodfacts.org/additives.xml ====== Individual Additive ====== * https://world.openfoodfacts.org/additive/e301-sodium-ascorbate.json * https://world.openfoodfacts.org/additive/e301-sodium-ascorbate.xml ====== Getting suggestions for additives ====== * https://world.openfoodfacts.org/cgi/suggest.pl?lc=fr&tagtype=additives&string=e =====Allergens of products===== ======List of allergens====== * https://world.openfoodfacts.org/allergens.json * https://world.openfoodfacts.org/allergens.xml ======Individual allergen====== * https://world.openfoodfacts.org/allergen/fish.json * https://world.openfoodfacts.org/allergen/fish.xml ======Getting suggestions for allergens ====== * https://world.openfoodfacts.org/cgi/suggest.pl?lc=fr&tagtype=allergens&string=a ==== Nutrition values ==== ===== Nutrition data ===== ====== General structure ====== 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 fact 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 ""; * 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. ====== List of nutrition keys ====== 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) * fruits_vegetables_nuts_estimate_100g : estimate by manually looking at the list of ingredients * 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 grades (Nutriscore, UK grades) ===== * For more details, see [https://fr.openfoodfacts.org/score-nutritionnel-experimental-france the page explaining the grade computation] * nutrition_score_debug: lets you see the calculations made <pre>"nutrition_score_debug":" -- energy 3 + sat-fat 6 + fr-sat-fat-for-fats 6 + sugars 0 + sodium 6 - fruits 0% 0 - fiber 0 - proteins 5 -- fsa 15 -- fr 15"
- Nutrition Grade Value
"nutrition_grades":"d" "nutrition_grades_tags":["d"] "nutrition_grade_fr":"d"
Nutrition Grade Images
No formal API is available, but you can use:
https://static.openfoodfacts.org/images/misc/nutriscore-a.svg https://static.openfoodfacts.org/images/misc/nutriscore-b.svg https://static.openfoodfacts.org/images/misc/nutriscore-c.svg https://static.openfoodfacts.org/images/misc/nutriscore-d.svg https://static.openfoodfacts.org/images/misc/nutriscore-e.svg
List of all nutrition grades
- https://world.openfoodfacts.org/nutrition-grades.json
- https://world.openfoodfacts.org/nutrition-grades.xml
List of products with a given nutrition grade (from A to E, including unknown)
- https://world.openfoodfacts.org/nutrition-grade/a.json
- https://world.openfoodfacts.org/nutrition-grade/a.xml
- https://world.openfoodfacts.org/nutrition-grade/e.json
- https://world.openfoodfacts.org/nutrition-grade/e.xml
- https://world.openfoodfacts.org/nutrition-grade/unknown.json
- https://world.openfoodfacts.org/nutrition-grade/unknown.xml
Nutrients levels
List of all nutrition levels
- https://world.openfoodfacts.org/nutrient-levels.json
- https://world.openfoodfacts.org/nutrient-levels.xml
List of products with fat in low quantity
- https://world.openfoodfacts.org/nutrient-level/fat-in-low-quantity.json
- https://world.openfoodfacts.org/nutrient-level/fat-in-low-quantity.xml
Unknown Nutrients
They might be unknown for a good reason…
List of Unknown Nutrients
- https://world.openfoodfacts.org/unknown-nutrients.json
- https://world.openfoodfacts.org/unknown-nutrients.xml
Individual Unknown Nutrients
- https://world.openfoodfacts.org/unknown-nutrient/sulfates.json
- https://world.openfoodfacts.org/unknown-nutrient/sulfates.xml
Packaging
- packaging : shape, material
- packaging_tags
- Packaging are not taxonomized yet.
List of Packagings
Individual Packaging
- https://world.openfoodfacts.org/packaging/cardboard.json
- https://world.openfoodfacts.org/packaging/cardboard.xml
Packaging images
No API is currently available. As a workaround, you can use the images from the server, or those folders.
https://github.com/openfoodfacts/openfoodfacts-server/tree/master/html/images/lang/jp/packaging https://github.com/openfoodfacts/openfoodfacts-server/tree/master/html/images/lang/de/packaging
Packager codes
- emb_codes
- emb_codes_tags
- first_packaging_code_geo : coordinates corresponding to the first packaging code indicated
List of Packager codes
- https://world.openfoodfacts.org/packager-codes.json
- https://world.openfoodfacts.org/packager-codes.xml
List of products with given Packager code
EMB (France specific)
- https://world.openfoodfacts.org/packager-code/emb-35069c.json
- https://world.openfoodfacts.org/packager-code/emb-35069c.xml
=EU Codes (Europe-wide) =
- https://world.openfoodfacts.org/packager-code/fr-38-012-001-ec.json
- https://world.openfoodfacts.org/packager-code/fr-38-012-001-ec.xml
= Note =
Other codes might be present, but we don't have specific support yet
List of Packaging cities
List of products with given Packaging city
- https://world.openfoodfacts.org/city/argenteuil-val-d-oise-france.json
- https://world.openfoodfacts.org/city/argenteuil-val-d-oise-france.xml
Contributors
Contributors
- https://world.openfoodfacts.org/contributor/teolemon.json
- https://world.openfoodfacts.org/contributors.json
Photographers
- https://world.openfoodfacts.org/photographer/teolemon.json
- https://world.openfoodfacts.org/photographers.json
Informers
- https://world.openfoodfacts.org/informer/teolemon.json
- https://world.openfoodfacts.org/informers.json
Product status & modification history
- 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
Status of products
For all possible values, please refer to the Global states taxonomy
List of States
Individual Status
- https://world.openfoodfacts.org/state/complete.json
- https://world.openfoodfacts.org/state/complete.xml
Getting suggestions for states
Last Edit Dates
List of Last Edit Dates
- https://world.openfoodfacts.org/last-edit-dates.json
- https://world.openfoodfacts.org/last-edit-dates.xml
List of products with a given last edit date
- https://world.openfoodfacts.org/last-edit-date/2014.json
- https://world.openfoodfacts.org/last-edit-date/2016-08.json
- https://world.openfoodfacts.org/last-edit-date/2016-05-19.json
- https://world.openfoodfacts.org/last-edit-date/2014.xml
- https://world.openfoodfacts.org/last-edit-date/2016-08.xml
- https://world.openfoodfacts.org/last-edit-date/2016-05-19.xml
Entry dates
List of entry dates
List of products with a given entry date
- https://world.openfoodfacts.org/entry-dates/2014.xml
- https://world.openfoodfacts.org/entry-dates/2016-08.xml
- https://world.openfoodfacts.org/entry-dates/2016-05-19.xml
- https://world.openfoodfacts.org/entry-dates/2014.json
- https://world.openfoodfacts.org/entry-dates/2016-08.json
- https://world.openfoodfacts.org/entry-dates/2016-05-19.json