Skip to content
Calorie API logoCalorie APIGet API key

API Reference

Barcode lookup API

A barcode lookup API resolves a UPC or EAN to nutrition. The local catalog is checked first, then Open Food Facts. A miss on both is HTTP 404. A hit returns product details, serving size, and macros per 100 g.

GET /api/v1/search/barcode/{upc}
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
Response example (Nutella)
{
  "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

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.