Open Food Facts Python SDK

Warnings

• gotcha The SDK is currently in beta, and the underlying API is subject to change. It is highly recommended to pin the exact version of `openfoodfacts` in your `requirements.txt` to avoid unexpected breaking changes.
  Fix: Always pin the library version (e.g., `openfoodfacts==5.0.1`) and review release notes before updating.
• breaking Version 5.0.0 introduced breaking changes related to improvements in the `ImageClassifier` module. If you were using image classification functionalities, your code might require updates.
  Fix: Review the official GitHub release notes and SDK documentation for `ImageClassifier` changes when upgrading to v5.0.0 or later.
• breaking Version 4.0.0 included a breaking change related to `warnings.deprecated` being exclusively available on Python 3.13+. If your application used `warnings.deprecated` in conjunction with the SDK on Python versions older than 3.13, you might encounter issues.
  Fix: Ensure your Python environment is >=3.10 as required by the library. If relying on `warnings.deprecated` features, verify compatibility with Python 3.13+.
• gotcha A `user_agent` is a mandatory parameter when instantiating the `API` object. This helps Open Food Facts identify usage and contact you if necessary.
  Fix: Always provide a descriptive `user_agent` string when initializing `openfoodfacts.API()`, e.g., `API(user_agent='YourAppName/1.0 - (https://your-app-website.com)')`.
• gotcha The API should not be used for downloading large amounts of data (e.g., the entire database). For bulk data access, Open Food Facts provides daily data dumps (CSV, JSONL, MongoDB dumps) that should be used instead.
  Fix: For bulk data, refer to the Open Food Facts 'Reusing Data' documentation to access data dumps. Use the API only for real-time product lookups or user contributions.
• gotcha Writing data (e.g., creating or updating products) to Open Food Facts requires authentication. You must provide a valid `username` and `password` when instantiating the `API` object.
  Fix: Initialize the API with authentication: `api = API(user_agent="...", username=os.environ.get('OFF_USERNAME'), password=os.environ.get('OFF_PASSWORD'))`.

Install

• pip install openfoodfacts Install stable version

Imports

• API

  from openfoodfacts import API

  The primary class for interacting with the Open Food Facts API. Other specific modules like APIVersion, Country, etc., can be imported for advanced configuration.

Quickstart

Instantiate the API client with a mandatory user agent, then retrieve product details by barcode or perform a text search. For write operations, authentication (username and password) is required.

import os
from openfoodfacts import API

# User-Agent is mandatory for API calls
# It's recommended to include your application name and version
user_agent = os.environ.get('OPENFOODFACTS_USER_AGENT', 'MyAwesomeApp/1.0 - (https://example.com/myapp)')

api = API(user_agent=user_agent)

# Get information about a product by barcode
product_code = "3017620422003"  # Example: Nutella
product_info = api.product.get(product_code, fields=["code", "product_name", "nutrition_grades", "ingredients_text"])

print(f"Product Name: {product_info.get('product', {}).get('product_name')}")
print(f"Nutri-Score: {product_info.get('product', {}).get('nutrition_grades')}")

# Perform a text search
search_results = api.product.text_search("mineral water")
print(f"Found {search_results.get('count')} products for 'mineral water'.")
if search_results.get('products'):
    print(f"First result: {search_results['products'][0].get('product_name')}")