# Open Food Facts Product Scraper (Nutrition Data JSON) (`steadfetch/open-food-facts-extractor`) Actor Official Open Food Facts product data: 4,888,333 products, 360,968 from Spain (7.4%). Search by barcode, brand, category or country; the Store example defaults to Spain. Monitor new or modified products and keep a daily Spain change history. Public ODbL data, pay per row. - **URL**: https://apify.com/steadfetch/open-food-facts-extractor.md - **Developed by:** [Steadfetch](https://apify.com/steadfetch) (community) - **Categories:** Other, Business - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 product delivereds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## Open Food Facts Scraper (Product Barcode and Brand Data) Extract food product metadata from the official [Open Food Facts](https://world.openfoodfacts.org) API v2: barcode, product name, brands, quantity and countries. The universe is **4,888,333 products** (measured 2026-11-01), of which **360,968 are from Spain** (7.4 %); the Store example defaults to Spain. Query by barcode, category, brand or country, with optional monitor mode that only emits products that are new or modified since the previous run, and a daily scheduled Spain change snapshot for history. HTTP + JSON only: no browser, no login and no API key. ### Universe and coverage | Figure | Value | Measured | | --- | --- | --- | | Products in Open Food Facts (the universe) | 4,888,333 | 2026-11-01, `/api/v2/search?page_size=1` | | Spain products | 360,968 (7.4 %) | 2026-11-01, `countries_tags_en=spain` | | Spain product edits over any 7-day window | >= 1,000 | 2026-11-01, `sort_by=last_modified_t` | | Default Store example | 10 Spain products | `countries: "en:spain"`, `maxResults: 10` | | `maxResults` default / cap | 100 / 5,000 (0.028 % / 1.4 % of Spain) | `input_schema.json` | The full 4.89 M-product database is never re-downloaded per run: Open Food Facts documents a limit of 10 search requests per minute, so a full Spain walk would take about 6.5 hours. The Actor covers the part a single run can serve, and the scheduled routine records the daily Spain change flow (new and modified products) as a growing series. ### What it does The Actor calls the official Open Food Facts v2 API and returns one dataset item per product: - **Product lookup:** `GET /api/v2/product/{code}.json` for a single barcode, or the documented bulk `code=a,b,c` lookup on the search endpoint. - **Structured search:** `GET /api/v2/search` filtered by `categories_tags`, `brands_tags` and `countries_tags`, paginated up to `maxResults` (default 100, maximum 5,000) and deduplicated by `code`. - **Monitor mode:** keeps a per-query deduplication state in a named key-value store and emits only products that are new or whose `last_modified_t` grew since the previous run with the same filters. Re-running a monitor never bills the same unchanged product twice. - **Daily Spain history (scheduled routine):** a Spain-only monitor run started by the Steadfetch account with the internal `saveSnapshot` flag writes the day's Spain change snapshot and a change report to the Steadfetch S3 bucket, so a consumer can build a Spain food-catalogue series without re-scraping. Customers and the daily QA never write. - **Schema validation:** every item is validated against `.actor/dataset_schema.json` before it reaches the dataset. With `strictSchema: true` (the default) an invalid item fails the run instead of pushing malformed data. The Actor uses **only the official API**: the legacy `cgi/search.pl` endpoint (returning 503 on 2026-10-20) is deliberately not implemented. Open Food Facts API v2 does not support free-text search, so the optional `search` field is a local, case-insensitive substring filter on `product_name` and `brands` applied to the structured results. It cannot be used alone: a run with only `search` fails loudly instead of scanning the whole database. The data is published by Open Food Facts under the [Open Database License (ODbL) 1.0](https://opendatacommons.org/licenses/odbl/1-0/); attribution: Open Food Facts contributors, . The Actor returns product metadata only. Contributor fields (creator, editors, informers, photographers, uploaders) and any personal data are never mapped. ### Example output ```json { "url": "https://world.openfoodfacts.org/product/0737628064502", "scrapedAt": "2026-10-20T12:00:00.000Z", "code": "0737628064502", "product_name": "Thai peanut noodle kit includes stir-fry rice noodles & thai peanut seasoning", "brands": "Simply Asia, Thai Kitchen", "quantity": "155 g", "countries": "France, United States", "source_url": "https://world.openfoodfacts.org/api/v2/product/0737628064502.json" } ``` `product_name` is always a string. Open Food Facts frequently stores an empty name; the Actor emits the empty string rather than inventing a value. `brands`, `quantity` and `countries` are omitted when the source has no value. Products without a barcode cannot satisfy the output schema and are skipped, never invented. ### Input Default Store example (10 Spain products): ```json { "countries": "en:spain", "maxResults": 10 } ``` Product lookup by barcode: ```json { "codes": ["0737628064502"], "maxResults": 10 } ``` A Spain category monitor: ```json { "mode": "monitor", "categories_tags": ["en:yogurts"], "countries": "en:spain", "maxResults": 500 } ``` | Field | Type | Description | | --- | --- | --- | | `mode` | `extract` or `monitor` | Default `extract`: emit every matching product. `monitor`: emit only products new or modified since the previous run with the same filters (deduplicated by `code`). | | `codes` | array of strings | Open Food Facts barcodes, for example `["0737628064502"]`. Bulk lookups are deduplicated by code. | | `categories_tags` | array of strings | Category tags such as `en:yogurts` or `en:breakfast-cereals`. Multiple values are combined with OR. | | `countries` | string | Country tag or plain name, for example `en:united-states` or `United States`. Comma-separated values are combined with AND by the API. | | `brands` | string | Brand tag or name, for example `danone`. Passed to the official `brands_tags` filter. | | `search` | string | Optional case-insensitive substring filter on `product_name` and `brands`, applied to the structured results. Not a full-text search and cannot be used alone. | | `maxResults` | integer | Default 100, maximum 5,000. Paging stops as soon as that many products are collected. | | `strictSchema` | boolean | Default `true`; fail the run on schema violations. | | `saveSnapshot` | boolean | Internal, default `false`: scheduled Spain series only. Writes the daily Spain change snapshot to the Steadfetch bucket only on a run started by the Steadfetch account. Not part of the public workflow. | Provide at least one of `codes`, `categories_tags`, `brands`, `countries` or a structured filter plus `search`. The client throttles every request (about 6.5 s between search calls, about 4.2 s between product calls, matching the API's 10/min and 15/min limits), sends a custom User-Agent, and retries 429/5xx and the API's HTML "temporarily unavailable" body with exponential backoff. Monitor state is keyed by the filter signature (`codes`, `categories_tags`, `countries`, `brands`, `search`) and lives in the `open-food-facts-monitor-state` key-value store, so it survives between scheduled runs. ### Project structure ``` .actor/actor.json Actor definition (payPerEvent, dataset schema, output schema) .actor/input_schema.json INPUT options (mode, codes, categories_tags, countries, brands, search, maxResults) .actor/dataset_schema.json Item JSON Schema (fields) + table view for the Store .actor/output_schema.json Output schema: links the default dataset as the results output .actor/pay_per_event.json PPE pricing (two synthetic platform events + monitor-check) src/fetch.ts Open Food Facts API v2 client: filters, pagination, throttling, retries src/extract.ts Pure mapping and deduplication (fixture-tested, no network) src/monitor.ts Pure monitor-state key and new/modified selection rules src/ppe.ts Pay-per-event names and the monitor-check charge helper src/s3-save.ts Daily Spain change snapshot + change report (D-33 owner guard) src/main.ts Entry point: fetch, validate, push, persist monitor state, charge, snapshot src/validate-output.ts Ajv validator shared by the run and the tests test/ Offline JSON fixtures and Vitest suites ``` ### Pay-per-event pricing The Actor uses Apify **pay-per-event** pricing with the two synthetic platform events plus the reserved `monitor-check` event for monitor runs: | Event | Charged when | Price | | --- | --- | --- | | `apify-actor-start` | a run starts (synthetic, automatic) | 0.00005 USD per run (Apify-recommended default; includes 5 seconds of free compute) | | `apify-default-dataset-item` | a validated product is saved to the dataset (synthetic, automatic) | 0.002 USD per product = **2.00 USD per 1,000 products** | | `monitor-check` | once per watched query actually checked in a monitor run | 0.0005 USD per check = **0.50 USD per 1,000 checks** | The per-result charge stays on `apify-default-dataset-item`; there is no custom per-item event, so users are never billed twice for the same product. The `monitor-check` event exists because a monitor run that finds nothing new would otherwise only bill the run-start event, and it is charged only after the check completed and its state was persisted. Errors, empty results, retries, products without a barcode and duplicates skipped by monitor deduplication are never pushed, so they are never charged. The Open Food Facts niche has no rated Apify competitor with more than one review, and the closest reference is the Store's open-data band (0.0006-0.012 USD per event). The 2.00 USD per 1,000 price sits inside Steadfetch's 1-10 USD band and keeps a wide margin over the measured cost. #### Cost per 1,000 products and 1,000 checks A 1,000-product run needs at most 10 search requests (100 products per page) at the API's 10 requests/minute limit, a few minutes of a 256 MB container and no proxy. The API is free and the mapping is pure local computation: about **0.01 USD of compute plus the 0.00005 USD run-start event per 1,000 products**, well below **0.05 USD per 1,000**. At the 2.00 USD price the gross margin is above 96%. A monitor check is one throttled search request plus local deduplication: about 7 seconds of a 256 MB container and the 0.00005 USD run-start event. 1,000 checks therefore mean 1,000 run starts (0.05 USD) plus about two container-hours of compute; the 0.50 USD price sits inside the reserved 0.01-1.00 USD band and keeps the check fee far below a delivered result. ### Development ```bash npm install npm test # lint + typecheck + offline Vitest suites (no credit) npm run publish:check # Steadfetch publish gate npm run schemas:validate # apify-cli schema validation npm run smoke # local Apify run against the live API (no platform credit) ``` The default test suite runs against committed API fixtures and never touches the network or the Apify platform. It covers the real API response shape, both endpoints, pagination, rate-limit retries, monitor deduplication, malformed records and output-schema validation. Set `OFF_LIVE_TEST=1` to also run the opt-in live API check (product + search, no Apify credit). ### Daily Spain history (scheduled routine) A daily Apify routine runs a Spain-only monitor query and writes two objects to the Steadfetch S3 bucket: ``` actors/open-food-facts-extractor//spain-snapshot.json actors/open-food-facts-extractor//changes.json ``` - `spain-snapshot.json` is the day's Spain change snapshot: the products that are new or modified, with their `last_modified_t` and public product metadata. Accumulating the daily files gives a Spain food-catalogue series without re-scraping. - `changes.json` is the change report: checked / new / modified / unchanged counts, the previous and current `last_modified_t` watermarks, the universe figures and the query limits. Schema: `steadfetch.open-food-facts-daily-change-report.v1`. - **D-33 guard:** an Apify schedule cannot inject environment variables, so the routine opts in with `saveSnapshot: true` in its run input **and** the run must be started by the Steadfetch account (`APIFY_USER_ID`). Customer runs never write, even with the flag; daily QA runs of our account never send it. Only Spain data is written, and only product metadata: no contributor or personal fields. - The full 360,968-product Spain catalogue is not re-downloaded daily (10 search requests/minute would take about 6.5 hours). The series records the change flow, which is the daily signal: at least 1,000 Spain edits in any 7-day window. - One snapshot per UTC day; a same-day re-run replaces that day's objects. A failed upload never fails the run. ### FAQ **Does the Actor need a login, API key or paid subscription?** No. The Open Food Facts API v2 is public and keyless, and the Actor only uses its official endpoints. **Why no browser (Playwright)?** The source is a JSON API. HTTP + JSON is roughly 10x cheaper and faster than a browser; no JavaScript rendering is needed. **Why can't I search by product name only?** Open Food Facts API v2 does not support free-text search, and the legacy `cgi/search.pl` endpoint is not used. Use a category, brand, country or barcode filter, optionally with `search` as a local name/brand filter. **When am I charged?** Once per run start (`apify-actor-start`), once per validated product saved to the dataset (`apify-default-dataset-item`), and in monitor mode once per watched query checked (`monitor-check`). Extract runs and failed checks are not charged a `monitor-check`; a monitor check that finds nothing new costs only the start plus the check fee. **Where is the daily history?** The scheduled Spain routine writes `actors/open-food-facts-extractor//spain-snapshot.json` and `changes.json` to the Steadfetch S3 bucket. Customer and QA runs never write to the bucket. **Is the output schema stable?** Yes. New fields are added additively and `required` fields never change; your downstream code can rely on `url`, `scrapedAt`, `code`, `product_name` and `source_url`. **Can I request a new source?** Yes, open an issue in this repository describing the public source you want tracked. ### Maintenance This Actor is **tested daily**: automated runs keep the source reachable and the output schema valid. The daily Spain routine is the only writer of the bucket series; customer and QA runs never write. Schema changes are announced through repository releases. ### Attribution and licence Product data: Open Food Facts contributors, licensed under the Open Database License (ODbL) 1.0. If you use this data publicly, keep the attribution and share derivative databases under the same licence. The Actor code itself is Steadfetch proprietary (UNLICENSED). # Actor input Schema ## `mode` (type: `string`): extract: emit every matching product. monitor: emit only products that are new or modified since the previous run with the same query (deduplicated by code). ## `codes` (type: `array`): Open Food Facts barcodes (for example 0737628064502). Bulk lookups are deduplicated by code. ## `categories_tags` (type: `array`): Category tags such as en:yogurts or en:breakfast-cereals. Multiple values are combined with OR. ## `brands` (type: `string`): Brand tag or name, for example danone. Passed to the official brands_tags filter. ## `countries` (type: `string`): Country tag or name. The Store example defaults to Spain (en:spain, 360,968 products); other valid values are en:united-states, en:france, etc. Comma-separated values are combined with AND by the API. ## `search` (type: `string`): Optional case-insensitive substring filter applied to product_name and brands of the structured results. Open Food Facts API v2 has no full-text search, so this cannot be used alone. ## `maxResults` (type: `integer`): Maximum number of products to save to the dataset. Default 100, maximum 5000. ## `strictSchema` (type: `boolean`): Fail the run when an item does not match the OUTPUT schema. Keep enabled: Steadfetch never publishes Actors without output-schema validation. ## `saveSnapshot` (type: `boolean`): Internal use: scheduled Spain series only. When enabled on a run started by the Steadfetch account, the run also writes the day's Spain change snapshot and change report to Steadfetch object storage. Customer runs never write, even with this flag on; QA runs of our account do not pass it. ## Actor input object example ```json { "mode": "extract", "codes": [ "0737628064502" ], "categories_tags": [ "en:yogurts" ], "brands": "danone", "countries": "en:spain", "search": "yogurt", "maxResults": 10, "strictSchema": true, "saveSnapshot": false } ``` # Actor output Schema ## `results` (type: `string`): Dataset items validated against the item schema in dataset_schema.json (fields). # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "extract", "countries": "en:spain", "maxResults": 10, "strictSchema": true }; // Run the Actor and wait for it to finish const run = await client.actor("steadfetch/open-food-facts-extractor").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "extract", "countries": "en:spain", "maxResults": 10, "strictSchema": True, } # Run the Actor and wait for it to finish run = client.actor("steadfetch/open-food-facts-extractor").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}") for item in client.dataset(run.default_dataset_id).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "extract", "countries": "en:spain", "maxResults": 10, "strictSchema": true }' | apify call steadfetch/open-food-facts-extractor --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,steadfetch/open-food-facts-extractor" } } } ``` The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer ` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations). ## OpenAPI specification Download the OpenAPI definition: https://api.apify.com/v2/actors/fsTo3TspF8Xu5Tnkf/builds/hhsgOmdbNLISSiLOZ/openapi.json