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 may 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 want to learn what the Open Food Facts data is used for. It is not mandatory, but we would appreciate it if you 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 it.

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)

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

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

If you need to fetch a significant fraction of the database, it's recommended to download 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 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 you (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 (contact@myapp.com).

  • READ operations (getting info about a product, etc...) do not require authentication except 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. From there, you then have two alternatives:

  • The preferred one: Use the login API to get a session cookie and use this cookie in your subsequent request to be authenticated. However, the session must always be used from the same IP address, and you have a maximum of sessions per user.
  • 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 request, 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.

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.

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 to facilitate the usage 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.