Open Data

What the packs are

Each pack is a single SQLite database holding the products of one country, derived from the Open Food Facts database. A pack carries product identity, ingredients, additives, labels, allergens, categories and nutrition grades — the fields a halal and dietary verdict is computed from.

The packs are rebuilt weekly from the public Open Food Facts data dump, so each release is a snapshot rather than a live mirror. They contain no product images: images stay on Open Food Facts, which serves them under their own terms.

Every file is compressed with zstandard, so a pack is downloaded as a .sqlite.zst file and decompressed before it is opened.

Start from the manifest — it is the only stable URL, and it names the current version of every pack:

https://packs.halalapp.app/v1/manifest.json

The manifest is a JSON document with these top-level keys:

• schema_version — the version of the SQLite schema described below. A reader that does not know this number should not open the packs.
• generated_at — when this build ran, as an ISO 8601 timestamp.
• off_dump_revision — the Open Food Facts data dump the build consumed, so a pack can be traced back to its source.
• source — where the data came from: the Open Food Facts site and the exact dump the build read.
• license — the licence terms in machine-readable form: the ODbL on the database, the DbCL on its contents, and the attribution string to carry.
• verify — the build-wide totals of the acceptance check described below.
• packs — one entry per pack.

Each entry of packs carries:

• id , name and country_tag — the pack, its coverage, and the Open Food Facts facet it was filtered on ( null for the world pack, which is filtered on nothing).
• version , key and url — the release stamp, the object key it is stored under, and the URL to fetch it from.
• bytes and sha256 — the size and the SHA-256 of the compressed .sqlite.zst bytes, so a download can be checked before it is decompressed.
• raw_bytes and sha256_raw — the same two for the decompressed SQLite file, so the decompression can be checked too.
• product_count and vacuumed — how many products the pack holds, and whether the file was vacuumed before it was compressed.
• verify — the acceptance check, as checked , matched and skipped . Before a pack is published, a sample of its most-scanned barcodes is read back out of the built file and compared with the live Open Food Facts API, so the counts say how far the snapshot had already drifted from the source at build time. It is not a download check — that is what the two hashes are for.

Every pack URL follows one template, with the id and the version taken from the manifest entry rather than typed by hand:

https://packs.halalapp.app/v1/{packId}/{version}/{packId}.sqlite.zst

A version is immutable, and each rebuild keeps the previous release alongside the new one — so a download already in progress keeps working across a rebuild. Older versions are removed, so a URL you fetched more than one release ago can return 404. Re-resolve the current version through the manifest each time, and retry there on a 404.

A pack is a plain SQLite database with two tables. Nothing in it is specific to our app: it is the Open Food Facts fields we keep, in the shape we keep them.

products

One row per product, keyed by code — the barcode — as a TEXT PRIMARY KEY . The other columns are:

• product_name and product_name_i18n — the name in the product's own language, and a JSON object keyed by language code ( en , fr , es , de , ar , tr , ur , ru , id , ms ) holding the translated names.
• brands , quantity , packaging and lang — the product's identity fields and its own language code.
• ingredients_text and ingredients_text_i18n — the ingredient list, with the same per-language JSON object as the name.
• ingredients_tags , ingredients_analysis_tags , additives_tags , labels_tags , allergens_tags and traces_tags — the analysed ingredient, additive, label and allergen facets.
• categories , categories_tags , countries_tags and stores_tags — where the product sits and where it is sold.
• nutriscore_grade , nova_group and ecoscore_grade — the Open Food Facts scores, exactly as computed there.
• last_modified_t — the product's last Open Food Facts edit, as a Unix timestamp.

Every column whose name ends in _tags holds the Open Food Facts tags comma-joined into one string, in their original en: -prefixed form, so nothing about their structure is lost.

meta

A key/value table describing the pack itself: schema_version , pack_id , country_tag , generated_at , off_dump_revision , product_count , vacuumed , data_license , content_license , attribution and source_url — the last four naming the ODbL, the DbCL, an attribution notice and the Open Food Facts address, so a pack that travels on its own still carries its licence.

Open Food Facts

None of this exists without the contributors of  Open Food Facts , who photograph, type in and correct the products these packs are built from. Their own database and the terms it is offered under are documented at  world.openfoodfacts.org/data .

If you reuse these packs, tell Open Food Facts about it — they keep a public list of reuses, and a reuse they know about is one more argument for the people who fund and maintain the database. Write to them, or to us at  [email protected] .