Open Food Facts Scraper (Product Barcode and Brand Data)

Extract food product metadata from the official Open Food Facts 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; attribution: Open Food Facts contributors, https://world.openfoodfacts.org. The Actor returns product metadata only. Contributor fields (creator, editors, informers, photographers, uploaders) and any personal data are never mapped.

Example output

{
    "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):

{
    "countries": "en:spain",
    "maxResults": 10
}

Product lookup by barcode:

{
    "codes": ["0737628064502"],
    "maxResults": 10
}

A Spain category monitor:

{
    "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

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/<YYYY-MM-DD>/spain-snapshot.json
actors/open-food-facts-extractor/<YYYY-MM-DD>/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/<YYYY-MM-DD>/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).