• Add product/<BARCODE> to locate the product by it’s barcode.

Get a country-specific nutrients ordered list. It changes based on country and is useful both to show a nutrition table or a nutrition input form.

https://fr.openfoodfacts.org/cgi/nutrients.pl

• Add es. prefix to get only Spanish products.
• Add json=true to get a JSON response.

• Add us. prefix to get only US products.
• Add json=true to get a JSON response.
• Add a categories filter to get only breakfast cereals.

• Add it. prefix to get only Italian products.
• Add json=true to get a JSON response.
• Add a nutrition_grade filter to get food with Nutriscore ‘A’

• Add fr. prefix to get only French products.
• Add json=true to get a JSON response.
• Add multiple criteria (AND):
  • Add a categories filter to get only breakfast cereals
  • Add a nutrition_grade filter to get food with Nutriscore ‘A’
  • Add ingredients_from_palm_oil=without to get food without palm oil
  • Add additives=without to get food without additives

https://world.openfoodfacts.org/api/v2/search?code=8024884500403,3263855093192&fields=code,product_name

This API is limited by the largest header default limit of Nginx (8K). If you’re requesting EAN13 barcodes the server should allow you ⁸⁰⁰⁰⁄₁₄=571 products (I put 14 because you need to add a comma between each EAN).

Open Food Facts uses optical character recognition (OCR) to retrieve nutritional data and other information from the product labels.

Process

1. Capture the barcode of the product where you want to perform the OCR.
2. The Product Opener server software opens the image (process_image=1)
3. Product Opener returns a JSON response. Processing is done using Tesseract or Google Cloud Vision (recommended). The result is often cripped with errors with Tesseract, less with Google Cloud Vision.

Notes: * The OCR may contain errors. Encourage your users to correct the output using the ingredients WRITE API. * You can also use your own OCR, especially if to plan to send a high number of queries.

OCR with Google Cloud Vision

We recommend Google’s Vision API to detect and extract text from the images.

For more information about this product, see: https://cloud.google.com/vision/docs/ocr?hl=en

The image refresh API is to ensure we can request photo updates for select products to users for images which should be taken or re-taken (because they are too old, or possibly too small / blurry).

https://fr.openfoodfacts.org/api/v0/produit/3483130043180/beurre-cru-a-la-baratte-les-petites-laiteries?fields=images_to_update_fr

It returns a hash of image types + language code (only for the requested language code which should be the language of the app). The value is 0 for images we don’t have, or the age of the image (in seconds) for apps that want to add some context like "Our photo of the ingredients is 14 months old, could you take a new one?".

Sample API response

product: {
images_to_update_fr: {
packaging_fr: 0,
front_fr: 83734290,
ingredients_fr: 83734290
}
},

• [ ] Possible languages (already loaded in the app) https://static.openfoodfacts.org/data/taxonomies/languages.json
• [ ] Possible fields (front, ingredients, nutrition, packaging)

Pseudo code to generate button text

for field in images_to_update_fr: if field.value=0 verb = “take” else: verb = “refresh” fieldname = field.split.before(””) fieldlanguage = field.split.after(””) button_text = fetch_button_text(field_name, field_language, verb)

Strings to combine (suffix the language at the end)

“Take %s picture” “Refresh %s picture” “ingredients” “front” “nutrition” “packaging”

Optional - mention how old the image is

How to convert seconds in human readable format: 83734290 = 2 years and 7 months (example routine to convert) - https://stackoverflow.com/questions/29681328/convert-seconds-into-years-months-weeks-hours-minutes-and-seconds

Send the right query based on the initial field in images_to_update_fr

• Do not use the computed values in the pseudo code
• Probably refactor the methods we currently have to pass the field name, and make it future proof if we want to add new image fields.

This section includes the parameters you can add to make READ / SEARCH / WRITE requests.

URL Parameters

Country code

A country code is prefixed to the domain name openfoodfacts.org, e.g: fr.: it allows filtering all products from a specific country.

You can use world. to display products from all over the world or use one of the Alpha 2 codes as per ISO-3166-1.

Examples: - United States: us - France: fr - Spain: es

You can find the full list of supported country codes in the Countries taxonomy.

Important! Using a specific country code will also change the naming of the response fields, see language code.

Language code

A language code can be added after the country code to specify the language of the response fields, e.g: https://<cc>-<lc>.openfoodfacts.org

Example:

https://fr.openfoodfacts.org/categorie/pizzas.json

• Products returned are sold in France.
• Names of the response fields are in French.

Example 2:

https://fr-en.openfoodfacts.org/category/pizzas.json

• Products returned are sold in France.
• Names of the response fields are in English.

The language codes supported are based on the ISO Standards 639-1.

You can find the full list of supported language codes in the Languages taxonomy.

API Version

Current version number of the Open Food Facts API. For now, only version 0 is available. To be represented as: /api/v0

Results per page

page_size # page_size

• 20 # 20
• 50 # 50
• 100 # 100
• 250 # 250
• 500 # 500
• 1000 # 1000

Pagination

• page=1

Format

• json=true (recommended)
• xml=true

Output fields

Filtering the output fields reduces the payload size, the bandwith needed and the download time. To filter the fields, simply add the “fields” parameter to your search query. Example to retrieve only the generic_name: https://world.openpetfoodfacts.org/api/v0/product/20106836.json?fields=generic_name

This section includes the parameters you can add to make SEARCH requests.

URL Parameters

You can use any of the fields used on the website search form.

There are three types of parameters you can use to filter the results:

• Criteria
• Ingredients
• Nutriments

Criteria

Every time you use a criterion in your query, you must use the following tags:

• tagtype_0=categories
• tag_contains_0=contains
• tag_0=cereals

Example: https://world.openfoodfacts.org/cgi/search.pl?action=process&tagtype_0=categories&tag_contains_0=contains&tag_0=cereals

Where tagtype_0 can be one of the following:

• brands
• categories
• packaging
• labels
• origins
• manufacturing_places
• emb_codes
• purchase_places
• stores
• countries
• additives
• allergens
• traces
• nutrition_grades
• states
• contains
• does_not_contain

If you want to add more criteria to the query, increase the number of the tag. For example:

• tagtype_0=categories
• tag_contains_0=contains
• tag_0=cereals
• tagtype_1=label
• tag_contains_1=contains
• tag_1=kosher

Ingredients

Use the following parameters to include or exclude products containing any additives or ingredients from palm oil:

• additives

  • without_additives
  • with_additives
  • indifferent_additives

• ingredients_from_palm_oil

  • without
  • with
  • indifferent

• ingredients_that_may_be_from_palm_oil

  • without
  • with
  • indifferent

• ingredients_from_or_that_may_be_from_palm_oil

  • without
  • with
  • indifferent

Nutriments

You can also filter by nutriments (fat, sugars, energy, etc). To do so, you need to add three different parameters for each nutriment:

Example

• nutriment_0=energy
• nutriment_compare_0=lt
• nutriment_value_0=500

You can enter the following categories (nutriment_0): https://static.openfoodfacts.org/data/taxonomies/nutrients.json

Comparison of nutriments

Nutriment to compare

nutriment_compare_0

Operator

• lt # less than
• lte # less than or equal
• gt # greater than
• gte # greater than or equal
• eq # equal to
• nutriment_value_0 - Value to compare the nutrients to

Other search parameters

Output

• sort_by # sort by
• unique_scans_n # Popularity
• product_name # Product name
• created_t # Add date
• last_modified_t # Edit date

Linked Data

Whenever possible, Open Food Facts entities are linked to Wikidata, and in turn to Wikipedia. What this means is that you get access to a trove of additional encyclopedic knowledge about food. You can for instance get: Wikipedia articles about Camembert, the translation of salt in many languages, the molecular structure of a cosmetic ingredient… We provide the Wikidata QID, which is an unambiguous, stable and reliable identifier for a concept that will be useful to actually retrieve info from Wikipedia and Wikidata.

Example

https://world.openfoodfacts.org/categories.json

{"linkeddata":{"wikidata:en":"Q40050"},"url":"https://world.openfoodfacts.org/category/beverages","name":"Beverages","id":"en:beverages","products":14196}
Beverages >> https://world.openfoodfacts.org/category/beverages >> Q40050 >> https://www.wikidata.org/wiki/Q40050

This section includes the parameters you can add to make WRITE requests.

URL Parameters

user_id and password

No authentication is required for adding new products or adding images, although it is recommended.

Basic authentication is required for editing existing products.

You can create a global account to let the users of your app contribute without having to create individual credentials in the Open Food Facts site.

code

The word code, followed by the product barcode must be added to the URL:

https://us.openfoodfacts.org/cgi/product_jqm2.pl?code=0074570036004

Additional field values (new product)

You can add several values to a field by adding a comma between them.

Example: labels="labelA, labelB"

Reading back, use labels_tags to get an array of labels.

Additional field values (existing product)

To add additional information to an existing product field, add the prefix add_ to the parameter name.

POST https://us.openfoodfacts.org/cgi/product_jqm2.pl?code=0074570036004&user_id=myappname&password=******&add_categories=Desserts

Example

https://world.openfoodfacts.org/cgi/product_jqm2.pl?code=0048151623426&user_id=usernameexample&password=*****&product_name=Maryland%20Choc%20Chip&quantity=230g&brands=Golden%20Cookies&nutriment_energy=450&nutriment_energy_unit=kJ&nutrition_data_per=serving&ingredients_text=Fortified%20wheat%20flour%2C%20Chocolate%20chips%20%2825%25%29%2C%20Sugar%2C%20Palm%20oil%2C%20Golden%20syrup%2C%20Whey%20and%20whey%20derivatives%20%28Milk%29%2C%20Raising%20agents%2C%20Salt%2C%20Flavouring&traces=Milk%2C+Soya%2C+Nuts%2C+Wheat

Note: Use %20 for spaces (e.g. Maryland%20Choc%20Chip), & to concatenate parameters (e.g. quantity=230g&brands=Golden%20Cookies) and = to link the parameter to the value (e.g. nutriment_energy=450).

Breakdown:

• Server url + barcode: https://world.openfoodfacts.org/cgi/product_jqm2.pl?code=0048151623426
• User id: usernameexample`
• Password: password
• Product name: product_name=Maryland%20Choc%20Chip. Important: German umlauts are not converted (e.g. ä -> ae). For more information, see the FAQ section.
• Quantity: quantity=230g
• Brands: brands=Golden%20Cookies
• Energy: nutriment_energy=450
• Nutrition data per: nutrition_data_per=serving
• Ingredients: Fortified%20wheat%20flour%2C%20Chocolate%20chips%20%2825%25%29%2C%20Sugar%2C%20Palm%20oil%2C%20Golden%20syrup%2C%20Whey%20and%20whey%20derivatives%20%28Milk%29%2C%20Raising%20agents%2C%20Salt%2C%20Flavouring&traces=Milk%2C+Soya%2C+Nuts%2C+Wheat

Other Parameters:

• Nutriment_energy_unit: possible values are: kj, kcal. This value always applies to the nutriment_energy value. The normalized energy value, in kJ, can be found in energy_100g.

Status Codes

• Valid edits get the following response: { ... "status_verbose": "fields saved", "status": 1 ... }
• If the password entered is not correct, an HTML 200 code + an HTML page with a link to login is displayed.
• If the code is not correct, you get a 0 response.

About Copyright

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 when the product was added (UNIX timestamp format).
• created_datetime : date when the product was added (ISO8601 format: yyyy-mm-ddThh:mn:ssZ).
• last_modified_t : date when the product page was last modified.
• last_modified_datetime: date and time when the product was last modified.
• product_name : name of the product.
• generic_name: legal name of the product as regulated by the European authorities.
• quantity : quantity and unit.

Ingredients:

• ingredients_text: Raw list of ingredients. This will get automatically parsed and get used to compute the Eco-Score. You can either request if (if it exists) or send it in a specific language, e.g: ingredients_text_en
• traces: List of substances that might cause allergies that are present in trace amount in the product (this does not include the ingredients, as they are not only present in trace amount). It is taxonomized with the allergens taxonomy.
• traces_tags

Packages:

• packaging : shape, material. Example: Cardboard
• packaging_tags
• packaging_text : Recycling instructions as raw text eg: “Plastic bottle to recycle, Plastic cap to recycle”. This will get automatically parsed and get used to compute the Eco-Score. You can either request if (if it exists) or send it in a specific language, e.g: packaging_text_en for the above example
• emb_codes : packager code. Example: EMB 2013330
• emb_codes_tags

Brands:

• brands
• brands_tags

Categories:

• categories
• categories_tags

Location:

• origins : origins of ingredients
• origins_tags
• first_packaging_code_geo : coordinates corresponding to the first packaging code.
• manufacturing_places : places where the product was manufactured or transformed.
• manufacturing_places_tags
• cities
• cities_tags
• purchase_places: country, state and/or city where the product can be purchased. For example: Paris, France.
• stores: distributor name. Example: Tesco, Walmart, Carrefour.
• countries : list of countries where the product is sold.
• countries_tags

Labels

• labels: Example: vegan, fat free, Kosher.
• labels_tags

Producer

• producer
• producer_product_id
• producer_version_id

Value and Weight

• net_weight_value
• net_weight_unit
• drained_weight_value
• drained_weight_unit
• volume_value
• volume_unit

Images

• image_url
• image_small_url: simplified version of the url.

Energy

• Legacy
  • energy_unit: (string). The unit used in the energy_value field (example in JSON: “energy_unit”:“kJ”). Possible values are “kJ” or “kcal”.
  • energy_value: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in the unit specified in the field energy_unit (example in JSON: “energy_value”:“190”).
• Preferred method
  • energy-kj_unit: (string). The unit used in the field energy-kj_value (example in JSON: “energy_unit”:“kJ”). The only possible value is “kJ”;
  • energy-kj_value: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in kJ (example in JSON: “energy-kj_value”:“190”).
  • energy-kcal_unit: (string). The unit used in the field energy-kcal_unit (example in JSON: “energy_unit”:“kcal”). The only possible value is “kcal”;
  • energy-kcal_value: (string). The standardized value of a serving of 100g (or 100ml for liquids) for energy expressed in kcal (example in JSON: “energy-kcal_value”:“190”).

According to the European regulation, the ratio between values calculated in kJ and values calculated in kcal may differ from the standard conversion ratio of 4.184 (because of carried rounding errors). Both values might appear on the same product. In that case, the value in kJ will be the one returned in the legacy energy_unit and energy_value fields. If only one unit was provided (kJ or kcal), this unit will be returned in the legacy energy_unit and energy_value fields.

Additives:

• additives_n : number of food additives
• additives
• additives_tags

Miscellaneous:

• serving_size : serving size in g (or ml)
• serving_quantity
• no_nutriments : indicates if the nutrition facts are shown on the product label.
• ingredients_text
• allergens
• traces
• 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 https://world.openfoodfacts.org/nutriscore
• main_category
• other_information
• conservation_conditions: Example: Keep in a dry place.
• recycling_instructions_to_recycle
• recycling_instructions_to_discard
• nutrition_grade_fr_producer: declarative (printed on the packaging)
• recipe_idea
• customer_service: contact info of customer service.
• preparation: how to cook the food: microwave, oven, which temperature…
• warning: regulatory warning. Example: contains sorbitol.
• data_sources: source of data imported from producers.
• nova_group: system of grades for comparing the degree of processing of products. For more information, see: https://world.openfoodfacts.org/nova
• pnns_groups_1: disregard. Used to improve the nutriscore calculation.
• pnns_groups_2: disregard. Used to improve the nutriscore calculation.
• states: if the product is complete or if there is any information missing.

Environment
The Eco-Score needs to be queried according to the country of the user.
Due to the recent nature of the Eco-Score, the full APIs are documented in a separate document.
https://docs.google.com/document/d/1_5AeofpXbaKY9Rd3eeWmHIrhJE8GiPQ-Mfx1SCvpzME/edit?usp=sharing

Other nutrition keys

• carbon-footprint_100g : carbon footprint (indicated on some products). The unit is absolute grams of C02.
• ph_100g : pH (no unit)
• cocoa : minimal cacao content of the product in %. Important!: 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).
  For more information about the difference between the fr and uk nutri-scores see the FAQ section of this documentation.

Each nutrition fact consists of multiple fields which are represented by a key. The fields can also be found in the taxonomy translation file.

Field names are built by concatenating 3 concepts:

• The nutriment: “fiber”, “carbohydrate”, “salt”, etc…
• as sold vs prepared: “” (nothing is added for as sold) or “prepared” (for prepared products. Example: dehydrated soups, instant cocoa or convenience products like fries).
• The reference quantity: “100g” or “serving”

Example 1: 3.4 g of carbohydrates in the product as sold for 100g should be represented as:

carbohydrates_100g: 3.4

Example 2: 12 mg of zinc in the prepared product for a serving of 125 mL should be defined as:

zinc_prepared_serving: 0.012

Important: * Only the nutrition facts that are actually found on the packaging are present in the interface. * key_serving and Key_100g are values for the serving size or 100g. One of them is equal to “key”, the other one is converted.

Main nutrition keys:

• 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

The Attributes API is aimed at simplifying personal search and personalization of results for apps. It will be documented here once it’s ready.

Sample output:

https://fr.openfoodfacts.dev/api/v0/produit/3700214614266/chocolat-noir-perou-90-fruite-et-boise-alter-eco?fields=product_name,code,attributes_en

The Knowledge Panel API is currently a work in progress, aimed at simplifying information display for apps. It will be documented here once it’s ready.

Query allergens facet.