Open Food Facts API Documentation

1. General Information 2

As a developer, the Open Food Facts API allows you to get information about existing products and contribute to the products database.

Using the API, you can create apps to help people make better food choices and also provide data to enhance the database.

Check out how others are making use of the API at https://world.openfoodfacts.org/discover#reuses.


Data Disclaimer

The data contained in the Open Food Facts database are collected by users willing to selflessly contribute to the Open Food Facts initiative.

Therefore, no guarantees can be made for the accuracy, completeness, or reliability of the information provided. The user assumes the entire risk related to the use of data. You (or your users) are very welcome to provide fixes using the WRITE API.


Usage

You can use the Open Food Facts API for production use cases, as long as 1 API call equals 1 real scan by a user.


Do you know that we have ready-made SDKs for many programming languages ?


Domains

You can either use the global domain (https://world.openfoodfacts.org) or the local domains (https://fr.openfoodfacts.org, https://en.openfoodfacts.org …) for your API queries.


Endpoint

The Open Food Facts base API endpoint is https://world.openfoodfacts.org/api/2


Version

The current version of the API is 2 .


Authentication

READ and SEARCH operations

No authentication is required.

Add a User-Agent HTTP Header with the name of your app, the version, system and a url (if any), not to be blocked by mistake.

For example: User-Agent: NameOfYourApp - Android - Version 1.0 - www.yourappwebsite.com

WRITE operations

No authentication is required for adding new products or adding images.

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.

Parameters: * user_id: YourUserID * password: YourPassword

Checking you’re authentified

https://world.openfoodfacts.org/cgi/auth.pl

This endpoint returns status 200 or 403 if the user is authentified, either through the “session” cookie, or with the user_id and password parameters.


Environments

You can do READ / SEARCH operations on the prod environment running @ https://world.openfoodfacts.org.

You can do WRITE operations tests on the dev environment running @ https://world.openfoodfacts.net (user:off, password:off).


Security

Use the SSL version of the API: https://world.openfoodfacts.org


Error Codes

  • Product does not exist - HTTP code 200 + “status_verbose” : “product not found” + “Status” : 0. The request format is correct, but the product code does not exist in the database.
  • Wrong Password - HTTP code 200 + an HTML page with a link to log in. The request format is correct, but basic authentication is missing or the password entered is not correct.
  • Server down - HTTP codes 502/503/500
  • Redirect to another product - HTTP code 301

Disclaimer: The HTML code 404 is never thrown, even when a wrong password is entered. A feature request has been created and we are already working to fix this.


Rate limit

The API intended use is for apps, with one real user scan = one query. Automated queries are not supported. Please let us know in advance if you expect a high volume of calls. 

For more information, see: https://world.openfoodfacts.org/data


Cache

Some queries (facets) are caches. Should you need to disable the cache, you can pass the nocache=1 parameter.

Payload size reduction

Using the fields= parameter, you can reduce the response to only the fields you need.

Preliminary Considerations

The API development is in progress. This has several implications:

  • Open Food Facts and food products are constantly evolving.
  • Assume that data is less reliable until the product is marked as complete. You might want to filter incomplete products to avoid issues (this is especially relevant for allergens or food intolerances). Let your end users know about this and encourage them to exercise caution. Be upfront about possible risks. You can use the following template to inform your users: The data provided to you by this app are retrieved from the Open Food Facts database. No guarantees can be made for the accuracy, completeness, or reliability of the information provided. The data are provided “as is” and the originating source for the data (Open Food Facts) is not liable for any damages arising out of the use of the data.
  • Join our Slack Channel (https://slack-ssl-openfoodfacts.herokuapp.com) to get help, to share your thoughts, to let us know what you build with the API (contact@openfoodfacts.org or in the #API channel) or if you want to use WRITE operations.
  • You can also join the mailing list to be notified when improvements or changes are made to the API (we send only relevant information and very few e-mails. Don’t worry, you won’t be spammed). To join the mailing list, send an empty e-mail to api-subscribe@openfoodfacts.org to subscribe.

License

  • Do not send copyrighted photos or information using the API. Everything you send is OdBL for the data (https://opendatacommons.org/licenses/odbl/summary/index.html) and CC-BY-SA for the pictures (https://creativecommons.org/licenses/by-sa/4.0/). If you don’t own the data, you bear all the legal consequences.
  • Mention Open Food Facts as the source of the data.
  • Do not mix with other product databases (since you are then required to release them under OdBL, at your own legal risk).
  • Share any additions under the OdBL with the community.
  • By using any part of the API you have read and understood the license.

API Conventions

  • 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

Bugs

Do not hesitate to file a bug if you find an issue in the API or need an improvement. You can fill out the issue report on GitHub:


Downloading Data

It is recommended to use the live API to get updated data about products. However, in some cases, you may need a snapshot. They are available at:

  • https://world.openfoodfacts.org/data (all data)
  • https://[countrycode].openfoodfacts.org/data (data for a specific country).

Example: https://us.openfoodfacts.org/data - (See the list of countries in the Countries taxonomy)


Exporting Data

  • File Encoding: The file encoding is Unicode UTF-8.
  • CSV API: The character that separates fields is < tab > (tabulation).
  • JSON

API Roadmap

API Redesign: The API is far from perfect. It’s been decided to fix the most urgent bugs and start planning for a new version, more compliant with modern API standards. We need all the help we can get. Please join us on the #api Slack channel.

  • Project API: Additives
  • Project API: States
  • Project API: Statistics
  • Project API: Statistics Entry Dates

Other Projects

  • Open Pet Food Facts
  • Open Beauty Facts
  • Open Products Facts

More topics


Description

Get all products from Open Food Facts API.

Query
KeyValueDescription
jsontrue

2. READ requests 2

READ requests allow you to retrieve the nutritional data of a product with a barcode.

Description

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



Description

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

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

3. SEARCH Requests 6

SEARCH requests allow you to retrieve the nutritional data of products that comply with your search criteria. Check out the examples below to see what you can do !

Important! The search feature works on whole words only, not parts of words. Your application should not have “search as you type” features that send search queries with parts of words, since this causes performance issues on the Open Food Facts server.

Description

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


Headers
KeyValueDescription
Content-Typeapplication/json
Query
KeyValueDescription
actionprocess
jsontrue
Description

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


Query
KeyValueDescription
actionprocess
tagtype_0categories
tag_contains_0contains
tag_0breakfast_cereals
jsontrue
Description

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


Query
KeyValueDescription
actionprocess
tagtype_1nutrition_grades
tag_contains_1contains
tag_1A
jsontrue
Description

  • 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


Query
KeyValueDescription
actionprocess
tagtype_0categories
tag_contains_0contains
tag_0breakfast_cereals
tagtype_1nutrition_grades
tag_contains_1contains
tag_1A
ingredients_from_palm_oilwithout
additiveswithout
jsontrue

Description

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 800014=571 products (I put 14 because you need to add a comma between each EAN).

For cross platform sharing, you can also build a link to the web version of Open Food Facts: https://world.openfoodfacts.org/search?code=8024884500403,3263855093192

Query
KeyValueDescription
code8024884500403,3263855093192

List of the barcodes you want to get values for

fieldscode,product_name

Optional, to reduce payload size to just what you need

Description

https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=emb_codes&term=FR https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=categories&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=labels&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=ingredients&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=packaging_shapes&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=packaging_materials&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=packaging_shapes&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=languages&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=stores&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=brands&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=countries&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=traces&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=origins&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=states&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=nutrients&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=additives&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=allergens&term=f https://world.openfoodfacts.org/cgi/suggest.pl?tagtype=minerals&term=f

Query
KeyValueDescription
tagtypeemb_codes

The kind of values you want. Can be: emb_codes, categories, labels, ingredients, packaging_shapes, packaging_materials, languages, stores, countries, traces, states, origins, nutrients, additives, allergens, minerals

termFR

The value you’d like to get suggestions for

4. WRITE Requests 7

WRITE requests allow you to contribute new products and data to the Open Food Facts database.

Note: Please use the dev environment https://world.openfoodfacts.net for making test write calls (user:off, password:off). Remember to join the API channel on Slack before making a POST request !

Note:

Selecting, cropping and rotating photos are non-destructive actions. That means, the original version of the image uploaded to the system is kept as is. The subsequent changes made to the image are also stored as versions of the original image.

The actions described in this topic do not modify the image, but provide metadata on how to use it (the data of the corners in the case of selection and the data of the rotation). That is, you send an image to the API, provide an id, you define, for example, the cropping and rotation parameters and as a response, the server generates a new image as requested and you can call this new version of the image.

Query
KeyValueDescription
code04963406
user_idtest
passwordtest
brandsHäagen-Dazs
labelskosher

Description

Photos are source and proof of data. When you upload an image to Open Food Facts, the image is stored as is. The first photo uploaded for a product is auto-selected as the product’s “front” photo.

Before uploading photos:

  • Image Quality: Uploading quality photos of a product, its ingredients and nutrition table is very important, since it allows the Open Food Facts OCR system to retrieve important data to analyze the product. The minimal allowed size for photos is 640 x 160 px.

  • Upload Behavior: In case you upload more than one photo of the front, the ingredients and the nutrition facts, beware that only the first photo of each category will be displayed. (You might want to take additional images of labels, recycling instructions, and so on). All photos will be saved.

  • Label Languages: Multilingual products have several photos based on languages present on the packaging. You can specify the language by adding a lang code suffix to the request.

Product Image Upload (Perl):

The API route is product_image_upload.pl and you can specify from which perspective the photo was taken, by sending the imagefield to precise the angle, AND the image as a Multipart response in the matching field.

Parameters:

  • code: the barcode of the product
  • imagefield: (can be either: front | ingredients | nutrition | packaging)
  • imgupload_front : your image file if imagefield=front
  • imgupload_ingredients: your image file if imagefield=ingredients
  • imgupload_nutrition: your image file if imagefield=nutrition
  • imgupload_packaging: your image file if imagefield=packaging


Query
KeyValueDescription
code04963406
product_image_upload.pl/imgupload_frontcheeriosfrontphoto.jpg

Description

Note: Cropping is only relevant for editing existing products. You cannot crop an image the first time you upload it to the system.

Query
KeyValueDescription
code04963406
imgid2
idfront_en
x10
y10
x2145
y2145

Description

Although we recommend rotating photos manually and uploading a new version of the image, the OFF API allows you make api calls to automate this process.

You can rotate existing photos by setting angle to 90º, 180º or 270º clockwise.

Example:

POST https://world.openfoodfacts.org/cgi/product_image_crop.pl?code=3266110700910&id=nutrition_fr&imgid=1&angle=90

Query
KeyValueDescription
code04963406
idnutrition_fr
imgid1
angle90

Description

You have to deselect photos to remove languages that are not relevant to the product.

[DOCUMENTATION TBA]


Description

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

Set ocr_engine=google_cloud_vision to use it.

Query
KeyValueDescription
code04963406
idingredients_fr

You can also pass packaging_fr if you want to extract recycling instructions.

process_image1
ocr_enginegoogle_cloud_vision

Description

image 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
}
},

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.


Query
KeyValueDescription
fieldsimages_to_update_fr

5. Filtering 3

Advanced filtering is available to make fine-grained requests to the API.

Description

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




Description

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



Description

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

Make sure you don’t upload photos or information with copyright. Everything you send is OdBL for the data, and CC-BY-SA for the pictures. Be aware that you bear the legal consequences for uploading protected content.

6. Understanding responses 5

Description

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.


Description

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


Description

The tags suffix you find in some of the response fields refer to the normalized version of the values using the taxonomies. If a value is not taxonomized, it will be displayed in the original language. Example: es:leche (original language, original text). Note that not all special characters are supported. For more information, see the FAQ section.

Description

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

{ product: { product_name: “Chocolat noir Pérou 90% fruité et boisé”, code: “3700214614266”, attributes_en: [ { id: “labels”, name: “Labels”, attributes: [ { status: “known”, id: “labels_organic”, description_short: “Promotes ecological sustainability and biodiversity.”, title: “Organic product”, description: “Organic farming aims to protect the environment and to conserve biodiversity by prohibiting or limiting the use of synthetic fertilizers, pesticides and food additives.”, name: “Organic product”, match: 100 }, { status: “known”, description_short: “Fair trade products help producers in developping countries.”, id: “labels_fair_trade”, title: “Fair trade product”, description: “When you buy fair trade products, producers in developing countries are paid an higher and fairer price, which helps them improve and sustain higher social and often environmental standards.”, name: “Fair trade product”, match: 100 } ] } ] }, code: “3700214614266”, status: 1, status_verbose: “product found” }

Query
KeyValueDescription
fieldsattributes_en
Description

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.

The URL provided is just for courtesy, do not assume the response will be stable.

Query
KeyValueDescription
fieldsknowledge_panels

7. Metadata 15

This section describes metadata that are generated by Open Food Facts. Those are often static data that you might need down the road, like a list of all allergens, ingredients, countries, languages, nova groups, etc…

Taxonomies

A taxonomy is a regulated syntax definition for a property; for example, allergens. The definition includes all possible entries and translations into other languages (synonyms). Taxonomies are global and multilingual and do not vary by country.

The taxonomy file is static, it is created when a new taxonomy is built, it is stable and validated by the OFF team.

Taxonomies are not considered API calls, since they are static files.

https://world.openfoodfacts.org/data/taxonomies/allergens.json

The product’s category parents are indicated in the first line of the taxonomy:

 en:chocolate-advent-calendars: {
 parents: [
 "en:advent-calendars",
 "en:christmas-chocolates"
 ],

Facets

A facet refers to all the values that contributors add to a property. A facet includes the values defined in the taxonomy and the new values added by the contributors. Facet change constantly and their values are not validated. Facets vary by country.

Facet queries can be made to retrieve a list of the values that belong to a specific facet (for example, labels) and its product count.

A facet query has the following structure:

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

You can replace world with any of the country codes described in the Countries taxonomy.

The values of the facet that are not included in the taxonomy are marked with an asterisk (*).

See an example here: https://us.openfoodfacts.org/labels


Categories

A category is a “tag” used to classify foods in different groups. For example, cheeses. Categories can be freely entered by users. Food category is one of the facets of Open Food Facts. Other examples are allergens or additives.

Note that there is also a taxonomy of categories used to define as many as possible of the “tags” entered by users as known entries in the taxonomy.

The following query retrieves a list of all categories available:

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

You can retrieve a list of products that belong to a specific category. For example, “cheeses”:

https://world.openfoodfacts.org/category/cheeses.json

Note that the query has an additional parameter “category”.

Important! The categories hierarchy is not a tree but a lattice: each node can have several children, but also several parents.


Description

Query allergens facet.

See examples below for taxonomy and other queries.