Food Resolution

Resolve messy food text (brand names, product descriptions, or free-text meals) into clean, normalized nutrition data — including serving size, macros, ingredients (when available), plus match confidence metadata.

NutritionSignals is optimized for clean, normalized nutrition outputs — not for being a complete barcode directory. You’ll get the most accurate results when the input includes brand + product + size. Coverage improves continuously as the platform learns from real-world usage.

Quickstart Get an API key

Endpoint

POST /v1/foods/resolve

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.

Request body

Send a JSON payload with the food text you want resolved.

Request body

{
  "text": "Chobani Greek Yogurt, strawberry, 5.3 oz"
}

Required fields

text (string) — the unstructured food text to resolve

Optional fields

None in v1. (We may add optional country / locale later, but they’re not required right now.)

Tip: Cleaner input usually produces higher-confidence matches. Include a brand and serving size when you have them.

Try it

Paste your API key, enter food text, 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 Function URL / Base URL you enter below when you click Run.

Try it

POST /v1/foods/resolve

API Key (Bearer)

Tip: replace test_123 with your key from Authentication.

Food text

Function URL / Base URL

Calling:

https://api.nutritionsignals.com/v1/foods/resolve

Notes

This runs in the browser.
If you hit a CORS error, ensure your Firebase function has cors: true (or allow your docs domain).
Low confidence? Try adding brand + size (e.g. “Chobani … 5.3 oz”).

Response

{}

Examples

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

curl -X POST "https://api.nutritionsignals.com/v1/foods/resolve" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Chobani Greek Yogurt, strawberry, 5.3 oz"}'

Response

Example response (fields may vary based on availability):

Example response

{
  "id": "chobani_greek_yogurt_strawberry_5_3oz",
  "title": "Greek Yogurt",
  "brand": "Chobani",
  "variant": "Strawberry (Fruit on the Bottom)",
  "serving": { "amount": 5.3, "unit": "oz" },

  "image_cloud_url": "https://firebasestorage.googleapis.com/v0/b/calor-ai-ab538.firebasestorage.app/o/scans%2F1769182921854_003b840fd7bea200acf690a19d94fb1a927b783f4af5717793c570638b7d1f14.png?alt=media&token=4ace7ba1-e5f1-4d4c-a500-f7d6647d097a",
  "image_object_path": "scans/1769182921854_003b840fd7bea200acf690a19d94fb1a927b783f4af5717793c570638b7d1f14.png",
  "image_hash": "003b840fd7bea200acf690a19d94fb1a927b783f4af5717793c570638b7d1f14",

  "calories_kcal_total": 110,
  "protein_g": 11,
  "carbs_g": 15,
  "fat_g": 0,
  "fiber_g": 0,
  "sugar_g": 0,
  "sodium_mg": 0,

  "ingredients_full": [
    "Cultured nonfat milk",
    "Strawberries",
    "Cane sugar",
    "Water",
    "Fruit pectin",
    "Natural flavors",
    "Guar gum",
    "Locust bean gum",
    "Fruit and vegetable juice concentrate (for color)",
    "Lemon juice concentrate",
    "Live and active cultures (S. thermophilus, L. bulgaricus, L. acidophilus, Bifidus, L. casei, L. rhamnosus)"
  ],

  "match": {
    "confidence": 0.95,
    "source": "retailer_label",
    "normalized_from": "Chobani Greek Yogurt, strawberry, 5.3 oz"
  }
}

Behavior and expectations

Food Resolution is a best-effort resolver: it tries to normalize your input into the most likely canonical food result.

High confidence usually means the result is a strong match for the text you provided.
Low confidence usually means the input is ambiguous (missing brand/size, multiple similar products, or incomplete text).

Recommended handling for low-confidence matches:

Show the resolved result as a suggestion and let the user edit/confirm.
Prompt for more detail (brand, flavor, size, packaging).
Retry the request with the updated text.

If you’re building an input UX, asking for brand + item + size upfront is the simplest way to improve match quality.

Errors

401 — Missing/invalid API key
422 — Invalid request body (e.g. missing text)
429 — Rate limited
5xx — Server error

Read Errors

API endpoints

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/normalize
Description
Canonicalize nutrition inputs into a consistent format. (Coming soon)
Name
POST /v1/parse/nutrition-label
Description
Nutrition label OCR → structured macros. (Coming soon)
Name
POST /v1/analyze/food-image
Description
Food image → nutrition result. (Coming soon)
Name
GET /v1/scans/:scan_id
Description
Retrieve scan/audit details for debugging and support. (Coming soon)

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)