docs / barcode

Barcode Lookup API

base /barcode/v17 endpoints

post/barcode/v1/lookup1 credit

Barcode → one merged product: title/brand/category/image/description + dimensions/model + retailer offers&prices (UPCitemdb) + nutrition/ingredients/allergens if food (OFF). Includes check-digit validation, GTIN-13 normalization and issuing-country. source=auto merges both.

Parameter		Allowed / range	Description
barcode	required	—	The barcode to look up: UPC-A (12), EAN-13 (13), EAN-8 (8), GTIN-14, or ISBN-13 (978/979…). Spaces/dashes are stripped; check digit is validated (mod-10). Aliases: upc, ean, gtin, isbn, code.
source = auto	optional	auto · off · upcitemdb	Which open source(s) to query for lookup/batch. 'auto' merges both.
off_db = food	optional	food · beauty · petfood · products	Which Open-*-Facts sibling DB to search/lookup against when source=off. lookup auto-falls-back food→products when source=auto.

Try in playground →

post/barcode/v1/batch1 credit

Up to 20 barcodes in one call → array of merged products (input order preserved), each with its own source/validation. The competitor caps at 10.

Parameter		Allowed / range	Description
barcodes	required	—	Up to 20 barcodes — a JSON array or a comma-separated string (competitor caps batch at 10; we allow 20). Each is normalized + validated; results preserve input order with per-item source.
source = auto	optional	auto · off · upcitemdb	Which open source(s) to query for lookup/batch. 'auto' merges both.
off_db = food	optional	food · beauty · petfood · products	Which Open-*-Facts sibling DB to search/lookup against when source=off. lookup auto-falls-back food→products when source=auto.

Try in playground →

post/barcode/v1/search1 credit

Free-text product-name search across the open databases → product cards with pagination. Optional category scope. (Competitor: keyword/title/category search.)

Parameter		Allowed / range	Description
query	required	—	Free-text product-name keyword search (matches title across the open databases). Aliases: q, search, name, title.
category	optional	—	Optional Open-Food-Facts category tag to scope a search/brand query (e.g. 'sodas', 'chocolate-spreads', 'biscuits').
off_db = food	optional	food · beauty · petfood · products	Which Open-*-Facts sibling DB to search/lookup against when source=off. lookup auto-falls-back food→products when source=auto.
source = auto	optional	auto · off · upcitemdb	Which open source(s) to query for lookup/batch. 'auto' merges both.
page = 1	optional	1–1000	1-based page number (clamped 1-1000). Page forward with meta.next_page. Note: Open Food Facts throttles deep pages per-IP; the engine retries on a fresh proxy.
page_size = 20	optional	1–50	Results per page (1-50, default 20); out-of-range values are clamped.

Try in playground →

post/barcode/v1/by_brand1 credit

All products for a brand/manufacturer → product cards with pagination. (Competitor: brand + manufacturer search.)

Parameter		Allowed / range	Description
brand	required	—	Brand or manufacturer name → that brand's products. Aliases: manufacturer, brand_name.
category	optional	—	Optional Open-Food-Facts category tag to scope a search/brand query (e.g. 'sodas', 'chocolate-spreads', 'biscuits').
off_db = food	optional	food · beauty · petfood · products	Which Open-*-Facts sibling DB to search/lookup against when source=off. lookup auto-falls-back food→products when source=auto.
page = 1	optional	1–1000	1-based page number (clamped 1-1000). Page forward with meta.next_page. Note: Open Food Facts throttles deep pages per-IP; the engine retries on a fresh proxy.
page_size = 20	optional	1–50	Results per page (1-50, default 20); out-of-range values are clamped.

Try in playground →

post/barcode/v1/by_prefix1 credit

GS1 company-prefix (partial-barcode) search → products whose barcode starts with the given 6+ digits, plus the decoded issuing country. (Competitor: `491234*` partial method.)

Parameter		Allowed / range	Description
prefix	required	—	A GS1 company prefix — the first 6+ digits of a barcode (the competitor's `491234*` partial-barcode method). Returns products whose barcode starts with these digits + the decoded issuing country.
off_db = food	optional	food · beauty · petfood · products	Which Open-*-Facts sibling DB to search/lookup against when source=off. lookup auto-falls-back food→products when source=auto.
page = 1	optional	1–1000	1-based page number (clamped 1-1000). Page forward with meta.next_page. Note: Open Food Facts throttles deep pages per-IP; the engine retries on a fresh proxy.
page_size = 20	optional	1–50	Results per page (1-50, default 20); out-of-range values are clamped.

Try in playground →

post/barcode/v1/by_mpn1 credit

Manufacturer-Part-Number / model lookup → products with that MPN/model (UPCitemdb keyword index over the MPN). Exact model/mpn matches are surfaced first. Closes the competitor's mpn query-method (the proprietary mpn= DB-index isn't on the open tier, but the keyword index resolves real MPNs — Logitech 910-005565, Sony WH-1000XM4, Canon 2727C002 all verified).

Parameter		Allowed / range	Description
mpn	required	—	Manufacturer Part Number / model number → matching products. Aliases: model, model_number, part_number. Results whose model/mpn field equals the query are surfaced first (exact_match=true).
page = 1	optional	1–1000	1-based page number (clamped 1-1000). Page forward with meta.next_page. Note: Open Food Facts throttles deep pages per-IP; the engine retries on a fresh proxy.
page_size = 20	optional	1–50	Results per page (1-50, default 20); out-of-range values are clamped.

Try in playground →

post/barcode/v1/validatefree

Validate + decode a barcode WITHOUT a network call: mod-10 check digit, GTIN type, GTIN-13 normalization, GS1 issuing country, ISBN/Bookland detection. (We EXCEED the competitor here — it has no standalone validate.)

Parameter		Allowed / range	Description
barcode	required	—	The barcode to look up: UPC-A (12), EAN-13 (13), EAN-8 (8), GTIN-14, or ISBN-13 (978/979…). Spaces/dashes are stripped; check digit is validated (mod-10). Aliases: upc, ean, gtin, isbn, code.

Try in playground →

Example request · lookup

curl -X POST https://api.reefapi.com/barcode/v1/lookup \
  -H "x-api-key: $REEF_KEY" \
  -H "content-type: application/json" \
  -d '{"barcode":"5449000000996"}'

Response shape

{
  "ok": true,
  "data": { /* the result */ },
  "meta": {
    "latency_ms": 240,
    "record_count": 12,
    "completeness_pct": 100
  },
  "error": null
}