Barcode Lookup

Look up a UPC/EAN barcode and return the best-known normalized product result — including serving size, macros, ingredients (when available), plus match metadata.

Barcode lookup returns results only when NutritionSignals already knows the product (from previous usage or imported data). If a barcode is unknown, the API returns 404.

Quickstart Get an API key

Endpoint

GET /v1/barcode/{barcode}

Requests are made to:

Base URL

https://api.nutritionsignals.com

Authentication

All requests require an API key sent as a Bearer token in the Authorization header.

Authorization header

Authorization: Bearer YOUR_API_KEY

Don’t have a key yet? Read Authentication.

Path parameters

barcode (string) — UPC/EAN numeric barcode (digits only; separators are ignored)

Tip: You can pass barcodes with spaces/dashes — the API will strip non-digits.

Try it

Paste your API key, enter a barcode, click Run, and you’ll see the raw JSON response.

This runs in the browser. Your key is stored only in your browser (localStorage) so you don’t need to retype it. It’s sent only to the Base URL you enter below when you click Run.

Try it

GET /v1/barcode/{barcode}

API Key (Bearer)

Tip: Use test_123 to try quickly, or get a real key in Authentication.

Barcode (UPC/EAN)

Digits only. Spaces/dashes are OK — they’ll be ignored.

Function URL / Base URL

Calling:

https://api.nutritionsignals.com/v1/barcode/0123456789012

Notes

Unknown barcodes return 404.
If you need a fallback, use Food Resolution.

Response

{}

Examples

Use any standard HTTP client. Here are copy/paste examples:

curl -sS "https://api.nutritionsignals.com/v1/barcode/036000291452" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response

Example response (fields may vary based on availability):

Example response

{
  "barcode": "036000291452",
  "id": "036000291452",
  "title": "Peanut Butter (Creamy)",
  "brand": "Alaska",
  "barcodes": ["036000291452"],

  "calories_kcal_total": 190,
  "protein_g": 8,
  "carbs_g": 7,
  "fat_g": 16,
  "fiber_g": 2,
  "sugar_g": 3,
  "sodium_mg": 150,

  "nutrition_basis": "per_serving",
  "nutrition_per_100g": { "...": "..." },
  "nutrition_per_serving": { "...": "..." },

  "ingredients_text": "Roasted peanuts, sugar, salt...",
  "ingredients_full": ["... trimmed ..."],

  "match": {
    "source": "open_food_facts+ai",
    "confidence": 0.75,
    "normalized_from": "036000291452"
  },

  "image_url": null,
  "revision": "barcodeget-00010-yew"
}

Behavior and expectations

Barcode lookup returns the best-known record NutritionSignals has stored for the barcode.

200 means a product record was found.
404 means the barcode is unknown.

Recommended handling for unknown barcodes:

Let the user enter the product name manually and call Food Resolution.
If you have a label photo, use Food Image Analysis.

Errors

401 — Missing/invalid API key
404 — Barcode not found
422 — Invalid barcode
429 — Rate limited
5xx — Server error

Read Errors

API endpoints

Name
GET /v1/barcode/:barcode
Description
Look up a barcode and return the best-known normalized product result.
Name
POST /v1/foods/resolve
Description
Resolve unstructured food text into a canonical food object with serving size, macros, ingredients (when available), plus match confidence metadata.
Name
POST /v1/foods/analyze-image
Description
Upload a food image and receive a nutrition estimate plus confidence. (If enabled)
Name
GET /v1/scans/:scan_id
Description
Retrieve scan/audit details for debugging and support.

What’s next?

POST /v1/normalize — canonicalize nutrition inputs (coming soon)
POST /v1/parse/nutrition-label — label OCR → structured macros (coming soon)
POST /v1/analyze/food-image — image → nutrition result (coming soon)