docs
BackendAPI Reference

Products

Search, lookup, trending, alternatives, and verification.

country is a 2-letter code everywhere and defaults to IN.

Look up a product by barcode

GET /api/v1/products/search?barcode=<8–14 digits>&country=IN

No auth required. Resolution order: Redis (1h TTL) → Postgres → Open Food Facts (rate-limited to 12 req/min across the whole service). A product fetched from Open Food Facts is written to Postgres before it's returned, so the next look-up is local. A barcode Open Food Facts doesn't have either is remembered as a miss for 10 minutes. Every resolved look-up increments products.lookup_count.

Staying in step with Open Food Facts. Our row is a cache of theirs, not a fork — a read of an OFF-sourced row whose off_synced_at is 30+ days old kicks off a background refresh (opportunistic: skipped rather than queued if the per-minute budget has no free slot, since a refresh is never as urgent as a live scan). A refresh only rewrites the columns Open Food Facts owns — verified, verification_count, and lookup_count are ours and are never overwritten; a user_contributed row is never touched at all.

Response
{
  "status": "success",
  "cached": false,
  "data": {
    "id": "b18b6250-9d04-4cc4-9c09-a1b9ceec848a",
    "barcode": "8901030895564",
    "country": "IN",
    "product_name": "Aloo Bhujia",
    "brand": "Haldiram's",
    "image_url": "https://images.openfoodfacts.org/…/front.jpg",
    "nutrition_facts": {
      "energy_kcal": 546, "protein": 9.2, "carbs": 43.8, "fat": 36.4,
      "saturated_fat": 12.1, "trans_fat": 0, "fiber": 3,
      "sugar": 2.4, "sodium": 1.18, "cholesterol": null,
      "potassium": null, "calcium": null, "iron": null
    },
    "nutrition_per_serving": { "energy_kcal": 163.8, "sugar": 0.72 },
    "nutrient_levels": { "fat": "high", "saturated_fat": "high", "sugar": "low", "sodium": "high" },
    "serving_size": "30 g",
    "quantity": "200 g",
    "ingredients": "Gram flour, edible vegetable oil (palm), potato, salt…",
    "allergens": ["peanuts"],
    "traces": ["tree-nuts"],
    "labels": ["vegetarian", "no-added-sugar"],
    "additives": ["E330", "E500II"],
    "categories": ["snacks", "salty-snacks", "namkeen"],
    "source": "open_food_facts",
    "verified": false,
    "verification_count": 1,
    "nova_group": 4,
    "nutriscore_grade": "d",
    "is_vegan": true,
    "is_vegetarian": true,
    "is_palm_oil_free": false,
    "category": "namkeen"
  }
}

Everything in nutrition_facts is per 100 g, and sodium is in grams (Open Food Facts' convention), not milligrams. nutrition_per_serving is the same document scaled by serving_quantity — arithmetic only, absent rather than guessed when the pack states no serving size.

nutrient_levels is low / moderate / high per nutrient — Open Food Facts' own where they publish one, the UK FSA front-of-pack thresholds otherwise (with the separate drinks thresholds applied when the product is a beverage).

Three-valued fields, throughout

Dietary flags, allergens, traces, labels, additives, and categories are null when the source publishes nothing and [] / false when it publishes "none" — different claims about food that must never be collapsed into each other. traces (the "may contain" line) is kept apart from allergens on purpose: for an allergy it's often the line that actually decides it.

Tags travel as slugs with the locale prefix stripped ("tree-nuts", not "en:tree-nuts") — matchable and prettifiable, never a display string that can only be shown. Nutrient figures are sanity-checked before storage: negative, above 100g/100g, or above 900 kcal/100g values are dropped rather than stored (Open Food Facts is crowd-edited and does contain data-entry errors).

Search by name or brand

GET /api/v1/products/query?q=<2–60 chars>&country=IN&limit=20

Local catalogue first, ranked by trigram similarity against product_name and brand, then by popularity. When fewer than five local rows match, the list tops up from Open Food Facts' own search (its own 8 req/min budget, skipped rather than queued when spent — a thin result beats a slow one). Cached for 10 minutes.

Returns an array of product cards:

{
  "barcode": "8901030895564",
  "product_name": "Aloo Bhujia",
  "brand": "Haldiram's",
  "image_url": "https://…/front.jpg",
  "nutriscore_grade": "d",
  "nova_group": 4,
  "verified": false,
  "energy_kcal": 546,
  "sugar": 2.4,
  "sodium": 1.18
}

GET /api/v1/products/trending?country=IN&limit=10

The same card shape, ordered by lookup_count, then verification count, then recency — so a freshly seeded database still returns something. Products still named Unknown are excluded.

Same-shelf alternatives

GET /api/v1/products/alternatives?barcode=…&country=IN&sort_by=sugar&limit=3

Products sharing the scanned product's category, ranked on one nutrient. sort_by accepts sugar, sodium, fat, saturated_fat, energy_kcal, carbs (ascending — less is better), protein, fiber (descending — more is better), or score (Nutri-Score then NOVA). limit is clamped to 1–10.

Returns product cards with an extra sort_value (the ranked nutrient's per-100g figure). A product with no category returns [] — an unmatched shelf beats a wrong one.

Verification queue

GET /api/v1/products/needs-verification?country=IN&limit=12

Products below the 3-confirmation threshold that this device hasn't already voted on. Works without a token — sending one is what lets it skip what you've already voted on.

Confirm a product matches its label

POST /api/v1/products/verify · requires auth

{ "barcode": "8901030895564", "country": "IN" }

Who's confirming comes from the token, never from the body. Records a row in verifications, increments products.verification_count, flips verified to true at 3, busts the product's cache entry, and returns the refreshed product.

On this page