Changes

Jump to navigation Jump to search
22,828 bytes added ,  15:46, 30 March 2018
Created page with "=== 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 worl..."
=== 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 =====
<pre>
{
"status_verbose":"product not found",
"code":"32421",
"status":0
}
</pre>

===== 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 =====
* https://world.openfoodfacts.org/codes.json
* https://world.openfoodfacts.org/codes.xml
=====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=====
* https://world.openfoodfacts.org/brands.json
* https://world.openfoodfacts.org/brands.xml
=====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 =====
* https://world.openfoodfacts.org/languages.json
* https://world.openfoodfacts.org/languages.xml
=====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 =====
* https://world.openfoodfacts.org/language/italian/language/chinese.json
===== 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=====
* https://world.openfoodfacts.org/cgi/suggest.pl?lc=fr&tagtype=languages&string=a


====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=====
* https://world.openfoodfacts.org/labels.json
* https://world.openfoodfacts.org/labels.xml
=====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:
<pre>
https://static.openfoodfacts.org/images/lang/en/labels/eu-organic.135x90.svg
</pre>

A full list is available at:
<pre>
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
</pre>

=====Getting suggestions for labels=====
* https://world.openfoodfacts.org/cgi/suggest.pl?lc=fr&tagtype=labels&string=a

====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=====
* https://world.openfoodfacts.org/categories.json
* https://world.openfoodfacts.org/categories.xml
=====Individual category=====
* https://world.openfoodfacts.org/category/baby-foods.json
* https://world.openfoodfacts.org/category/baby-foods.xml
=====Getting suggestions for categories=====
* https://world.openfoodfacts.org/cgi/suggest.pl?lc=fr&tagtype=categories&string=a

==== 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 ======
* https://world.openfoodfacts.org/countries.json
* https://world.openfoodfacts.org/countries.xml
======Individual Country ======
* https://world.openfoodfacts.org/country/france.json
* https://world.openfoodfacts.org/country/france.xml
======Getting suggestions for Countries======
* https://world.openfoodfacts.org/cgi/suggest.pl?lc=fr&tagtype=countries&string=f
=====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======
* https://world.openfoodfacts.org/stores.json
* https://world.openfoodfacts.org/stores.xml
======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 =====
<pre>Do not make the assumption that the ingredient is or is not present based on this. Parsing errors happen.</pre>
====== 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
* The ingredients are not yet taxonomized on [https://world.openfoodfacts.org Open Food Facts]. They are taxonomized on [https://world.openbeautyfacts.org Open Beauty Facts]
* The taxonomies of ingredients need expansion: [[Global ingredients taxonomy]] (OFF), [https://en.wiki.openbeautyfacts.org/Global_ingredients_taxonomy Global ingredients taxonomy Open Beauty Facts]
====== List of detected ingredients ======
* https://world.openfoodfacts.org/ingredients.json
* https://world.openfoodfacts.org/ingredients.xml
====== 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) ======
* https://world.openbeautyfacts.org/cgi/suggest.pl?lc=fr&tagtype=ingredients&string=f


===== Vitamins and minerals detection =====


====== Vitamins ======
<pre>"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"]</pre>
====== Minerals ======
<pre>"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"]</pre>

====== Amino acids ======
<pre>"amino_acids_tags":["en:l-tryptophan"]</pre>

====== Other nutritional substances =====
<pre>"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"</pre>
* Nutrition Grade Value
<pre>
"nutrition_grades":"d"
"nutrition_grades_tags":["d"]
"nutrition_grade_fr":"d"
</pre>
====== Nutrition Grade Images ======
No formal API is available, but you can use:
<pre>
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
</pre>
====== 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=====
* https://world.openfoodfacts.org/packaging.json
* https://world.openfoodfacts.org/packaging.xml
=====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.
<pre>
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
</pre>

=====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 ======
* https://world.openfoodfacts.org/cities.json
* https://world.openfoodfacts.org/cities.xml
======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 ======
* https://world.openfoodfacts.org/states.json
* https://world.openfoodfacts.org/states.xml
======Individual Status ======
* https://world.openfoodfacts.org/state/complete.json
* https://world.openfoodfacts.org/state/complete.xml
======Getting suggestions for states======
* https://world.openfoodfacts.org/cgi/suggest.pl?lc=fr&tagtype=states&string=a
===== 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 ======
* https://world.openfoodfacts.org/entry-dates.json
* https://world.openfoodfacts.org/entry-dates.xml
====== 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

Navigation menu