Skip to content

Introduction to Open Food Facts API documentation#

Everything you need to know about Open Food Facts API.

Overview#

Open Food Facts is a food products database made by everyone, for everyone, that can help you make better choices about what you eat. Being open data, anyone can reuse it for any purpose.

The Open Food Facts API enables developers to get information like ingredients and nutritional values of products, and even add more facts to the products database. You can use the API to build applications that allow users to contribute to the database and make healthier food choices.

The current version of the API is 2.

Data in the Open Food Facts database is provided voluntarily by users who want to support the program. As a result, there are no assurances that the data is accurate, complete, or reliable. The user assumes the entire risk of using the data.

Before You Start#

Please read the Terms and conditions of use and reuse before reusing the data.

We like learning what the Open Food Facts data is used for. It is not mandatory, but we would appreciate it if you would tell us about your use case so that we can share them with the Open Food Facts community.

How to Best Use the API#

General principles#

  • You can search for product information, including many useful computed values.
  • Suppose we don't have the information you need on a specific product. In that case, you (or your users) can upload the product photos, and the backend (and our AI algorithms!) will process them, generating helpful info. The photos will also be available for the users of Open Food Facts and every other API user.
  • You could also ask your user to enter some of the information about the product (like name, category, and weight) so that they immediately get the computed info.

Generally, the more information we have about a product, the more we can compute.

Rate limits#

To protect our infrastructure, we enforce rate-limits on the API and the website. The following limits apply:

  • 100 req/min for all read product queries (GET /api/v*/product requests or product page). There is no limit on product write queries.
  • 10 req/min for all search queries (GET /api/v*/search or GET /cgi/search.pl requests)
  • 2 req/min for facet queries (such as /categories, /label/organic, /ingredient/salt/category/breads,...)

If these limits are reached, we reserve the right to deny you access to the website and the API through IP address ban. If your IP has been banned, feel free to email us to explain why you reached the limits: reverting the ban is possible.

If your requests come from your users directly (ex: mobile app), the rate limits apply per user.

If you need to fetch a significant fraction of the database, we recommend downloading the data as a CSV or JSONL file directly. If you need to download images in bulk, we have a guide for that.

If your users do not expect a result immediately (e.g., Inventory apps)#

  • Submit photos (front packaging/nutrition values/ingredients): the most painless thing for your users.
  • The backend (Product Opener) and Open Food Facts AI (Robotoff) will generate some derived data from the photos.
  • Over time, other apps and the Open Food Facts community will fill the data gaps.

If your users expect a result immediately (e.g., Nutrition apps)#

  • If you submit the product's nutritional values and category, you'll get the Nutri-Score.
  • If you submit the product ingredients, you'll get the NOVA group (about food ultra-processing), additives, allergens, normalized ingredients, vegan, vegetarian…
  • If you submit the product's category and labels, you'll get the Eco-Score (a rating of the product's environmental impact)

API Deployments#

The OpenFoodFacts API has two deployments.

Consider using the staging environment if you are not in a production scenario.

While testing your applications, make all API requests to the staging environment. This way, we can ensure the product database is safe.

Authentication#

We ask you to always use a custom User-Agent to identify your app (to not risk being identified as a bot). The User-Agent should be in the form of AppName/Version (ContactEmail). For example, MyApp/1.0 (myapp@example.com).

  • READ operations (getting info about a product, etc...) do not require authentication other than the custom User-Agent.
  • WRITE operations (Editing an Existing Product, Uploading images…) require authentication. We do this as another layer of protection against spam.

Create an account on the Open Food Facts app for your app (and notify reuse@openfoodfacts.org of the account name, so that we grant it special app privileges). From there, you have two options:

  • The preferred one: Use the login API to get a session cookie and use this cookie for authentication in your subsequent requests. However, the session must always be used from the same IP address, and there's a limit on sessions per user (currently 10) with older sessions being automatically logged out to stay within the limit.
  • If session conditions are too restrictive for your use case, include your account credentials as parameters for authenticated requests where user_id is your username and password is your password (do this on POST / PUT / DELETE requests, not on GET).

You can create a global account to allow your app users to contribute without registering individual accounts on the Open Food Facts website. This way, we know that these contributions came from your application.

We however ask that you send the app_name, app_version and app_uuid parameters in your write queries.

  • app_name=MyApp
  • app_version=1.1
  • app_uuid=xxxx: a salted random uuid for the user so that Open Food Facts moderators can selectively ban any problematic user without banning your whole app account.

Production and staging have different account databases, so the account you create in the production environment will only work for production requests. If you want to query (WRITE requests) the staging environment, you'll need to create another account there too.

Note: we're currently moving to a modern Auth system (Keycloak), so we will have new Auth options, hopefully this year.

Reference Documentation (OpenAPI)#

We are building a complete OpenAPI reference. Here is a list of the current API documentation available:

Tutorials#

Help#

  • Try the FAQ - to answer most of your questions.
  • Didn't get what you wanted? Contact the Team on the #api Slack Channel.
  • Report Bugs on the Open Food Facts GitHub repository.
  • Do you have an issue or feature request? You can submit it on GitHub too.
  • Are you interested in contributing to this project? See our Contribution Guidelines.

SDKs#

SDKs are available for specific languages for easier use of the API. We may have a wrapper for your favourite programming language. If we do, you can use it and improve it. However, If we don't, you can help us create it!

They will let you consume data and let your users contribute new data. Open-source contributors develop our SDKs, and more contributions are welcome to improve these SDKs. You can start by checking the existing issues in their respective repositories.

Warning: Before exploring any SDK, please read the Before You Start section.

Also, remember to check the API Reference Documentation first to verify if the problem is in SDK implementation or in the API itself.