{"id":4373,"library":"openfoodfacts","title":"Open Food Facts Python SDK","description":"The official Python SDK for the Open Food Facts project, providing a simple interface to the Open Food Facts API. It allows users to retrieve product information, perform text searches, and create/update products. It also includes helpers for taxonomies, data dump iteration, and OCR. The current version is 5.0.1. Please note that this SDK is still in beta, and its API is subject to frequent change. The library is actively maintained with major versions often released within weeks or months.","status":"active","version":"5.0.1","language":"en","source_language":"en","source_url":"https://github.com/openfoodfacts/openfoodfacts-python","tags":["food data","nutrition","api client","open data"],"install":[{"cmd":"pip install openfoodfacts","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for image processing features (e.g., OCR, image classification).","package":"pillow","optional":true},{"reason":"Required if using Redis caching features.","package":"redis","optional":true}],"imports":[{"note":"The primary class for interacting with the Open Food Facts API. Other specific modules like APIVersion, Country, etc., can be imported for advanced configuration.","symbol":"API","correct":"from openfoodfacts import API"}],"quickstart":{"code":"import os\nfrom openfoodfacts import API\n\n# User-Agent is mandatory for API calls\n# It's recommended to include your application name and version\nuser_agent = os.environ.get('OPENFOODFACTS_USER_AGENT', 'MyAwesomeApp/1.0 - (https://example.com/myapp)')\n\napi = API(user_agent=user_agent)\n\n# Get information about a product by barcode\nproduct_code = \"3017620422003\"  # Example: Nutella\nproduct_info = api.product.get(product_code, fields=[\"code\", \"product_name\", \"nutrition_grades\", \"ingredients_text\"])\n\nprint(f\"Product Name: {product_info.get('product', {}).get('product_name')}\")\nprint(f\"Nutri-Score: {product_info.get('product', {}).get('nutrition_grades')}\")\n\n# Perform a text search\nsearch_results = api.product.text_search(\"mineral water\")\nprint(f\"Found {search_results.get('count')} products for 'mineral water'.\")\nif search_results.get('products'):\n    print(f\"First result: {search_results['products'][0].get('product_name')}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Always pin the library version (e.g., `openfoodfacts==5.0.1`) and review release notes before updating.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially from 3.x onwards"},{"fix":"Review the official GitHub release notes and SDK documentation for `ImageClassifier` changes when upgrading to v5.0.0 or later.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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+.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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)')`.","message":"A `user_agent` is a mandatory parameter when instantiating the `API` object. This helps Open Food Facts identify usage and contact you if necessary.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Initialize the API with authentication: `api = API(user_agent=\"...\", username=os.environ.get('OFF_USERNAME'), password=os.environ.get('OFF_PASSWORD'))`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}