API Reference

Barcode Lookup

Resolve a UPC or EAN barcode to product and nutrition data. The API checks the local food database first; when no match is found, it falls back to Open Food Facts and returns only the fields needed for logging: product details, serving size, macros per 100 g (and per serving when available), and micronutrients when present.

curl "https://calorieapiadmin.com/api/v1/search/barcode/3017620422003" \
  -H "X-API-Key: your_api_key_here"

Path parameters

upcUPC/EAN barcode; any non-digit characters (dashes, spaces) are stripped

{
  "barcode": "3017620422003",
  "product": {
    "name": "Nutella",
    "brand": "Nutella",
    "category": "Pâtes à tartiner aux noisettes et au cacao, en:Pâtes à tartiner",
    "generic_name": "Pâte à tartiner aux noisettes et au cacao",
    "quantity": null,
    "ingredients": "sugar, palm oil, hazelnuts 13%, low-fat cocoa 7.4%, skimmed milk powder 6.6%, whey powder, emulsifiers: lecithins [soya], vanillin, gluten-free,",
    "allergens": [
      "milk",
      "nuts",
      "soybeans"
    ]
  },
  "serving": {
    "label": "100g",
    "quantity": null,
    "unit": "g"
  },
  "nutrition_per_100g": {
    "energy_kcal": 539,
    "protein_g": 6.3,
    "carbohydrates_g": 57.5,
    "fat_g": 30.9,
    "fiber_g": null,
    "sugars_g": 56.3,
    "saturated_fat_g": 10.6,
    "salt_g": 0.107,
    "sodium_g": 0.0428,
    "added_sugars_g": 38.35
  },
  "nutrition_per_serving": null,
  "micronutrients_per_100g": []
}

Response fields

barcodeNormalized UPC/EAN digits

product.nameProduct title

product.brandPrimary brand name

product.categoryFood category label

product.generic_nameShort product description when available

product.quantityPackage size when available

product.ingredientsIngredients text

product.allergensAllergen list

serving.labelHuman-readable serving size

serving.quantityNumeric serving amount when available

serving.unitServing unit (g, ml, etc.)

nutrition_per_100gMacros per 100 g: energy_kcal, protein_g, carbohydrates_g, fat_g, fiber_g, sugars_g, saturated_fat_g, salt_g, sodium_g, added_sugars_g

nutrition_per_servingSame macro fields per labeled serving when Open Food Facts provides serving data

micronutrients_per_100gVitamins and minerals per 100 g when present (name, amount, unit)

Open Food Facts raw payloads include thousands of metadata fields; this endpoint strips that down to logging-ready product and nutrition data, so the response shape is identical whether the product came from the local catalog or the fallback.

Handling misses

If neither the local database nor Open Food Facts knows the barcode, the API returns HTTP 404 with a "Food not found for barcode" message. A good pattern is to fall back to food search in your UI so the user can log the item manually.

Frequently asked questions

Which barcode formats are supported?

UPC and EAN barcodes. Pass the barcode in the URL path; any non-digit characters (dashes, spaces) are stripped automatically.

Is the Open Food Facts fallback automatic?

Yes. The lookup order is always local catalog first, then Open Food Facts, with a single normalized response shape either way, your client code does not need to know the source.

Why are some nutrition fields null?

Label data varies by product and region. Fields the source does not provide (for example fiber or per-serving values) are null rather than omitted, so your parsers stay simple.