API documentation

The NutrientGraph API: food search in five languages, lookup by id or barcode, nutrients for any portion, recipes and cooking yields. Generated from the OpenAPI 3.1 spec (openapi.json); every example response below is real output of the API on the current data.

Getting started

Get a free key: confirm your email with the link we send; the key is shown once. Manage it (usage, rotate, revoke) on the account page.
Send it in the X-API-Key header (or Authorization: Bearer).
Base URL: https://api.nutrientgraph.com.

export API_KEY=xmd_live_...
curl -s "https://api.nutrientgraph.com/v1/food/search?q=chicken+breast+roasted&lang=en&limit=3" -H "X-API-Key: $API_KEY"

Responses and provenance

Every successful response is {"data": …, "meta": …}. meta always has dataset, dataset_version, dataset_built_at, data_status, the sources with their licences, a disclaimer and your usage. The X-Dataset-Version header repeats the version so you can pin and diff.

Inside data, each value carries its provenance: the source, the record id or URL, the source field and value, and the retrieval date; where an AI judged something, the method and a confidence. Calculations list their inputs and method.

Errors and limits

Errors are {"error": {"code", "message", "details"}} with an HTTP status:

Error statuses
Status	Meaning and typical codes
400	Invalid request: `invalid_request`, `invalid_gtin`, `invalid_food_id`, `nutrient_values_not_accepted`
401	`missing_api_key`, `invalid_api_key`, `revoked_api_key`
404	`food_not_found`, `barcode_not_found`
422	Valid but not computable: `basis_not_per_100g`, `portion_without_grams`, `recipe_error`
429	`rate_limited` (see `Retry-After`), `quota_exceeded`, `too_many_attempts` (signup and key changes)
503	`dataset_not_loaded`

Rate limits are per key per minute; quotas are monthly units. Headers on every metered call: X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Limit, X-Quota-Used. Your usage by endpoint: GET /v1/usage. Errors cost nothing. See pricing for the limits of each plan.

MCP for AI agents

POST JSON-RPC 2.0 to /mcp (Streamable HTTP, JSON responses) with your key in X-API-Key. Methods: initialize, tools/list, tools/call, ping. Each REST operation below is a read-only tool with the same input schema; results come back as structuredContent with the same envelope and the same metering. Tool list: mcp-tools.json.

{
  "mcpServers": {
    "nutrientgraph": {
      "type": "http",
      "url": "https://api.nutrientgraph.com/mcp",
      "headers": {
        "X-API-Key": "YOUR_KEY"
      }
    }
  }
}

Tools: food_search, food_get, food_barcode, food_nutrients_for_portion, food_recipe_calculate, food_cooking_yields.

Endpoints

GET`/v1/food/search`

Search foods by name. Full-text search (prefix matching) over food names in English, French, German, Italian or Spanish: 15,961 generic foods (USDA, CIQUAL), 430,443 branded products (USDA Branded Foods, English) and 150 dishes. Without a type, generic foods and dishes come before branded products. Returns summaries; fetch a food by id for all values and provenance.

Cost: 1 unit. MCP tool: food_search.

Parameters
Name	In	Type	Required	Notes
`q`	query	string	yes	Search text
`lang`	query	string: en, fr, de, it, es, any	no	Language of the name; non-English names of USDA foods are machine translations (marked as such) Default en.
`type`	query	string: generic, branded, dish	no
`limit`	query	integer	no	Default 10.
`offset`	query	integer	no	Default 0.

Example

curl -s "https://api.nutrientgraph.com/v1/food/search?q=chicken+breast+roasted&lang=en&limit=3" \
  -H "X-API-Key: $API_KEY"

Response (200, real output of the API on the current data; long arrays trimmed)

{
  "data": {
    "query": "chicken breast roasted",
    "lang": "en",
    "type": null,
    "count": 3,
    "results": [
      {
        "id": "fdc:174608",
        "type": "generic",
        "name": "Chicken breast, roll, oven-roasted",
        "basis": "100 g",
        "energy_kcal_per_100": 134,
        "energy_provenance": {
          "source": "fdc_sr_legacy",
          "record_id": "174608",
          "source_nutrient_id": "1008",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "is_preferred": true,
        "matched_name": "Chicken breast, roll, oven-roasted",
        "matched_lang": "en"
      },
      {
        "id": "fdc:172963",
        "type": "generic",
        "name": "Chicken breast, oven-roasted, fat-free, sliced",
        "basis": "100 g",
        "energy_kcal_per_100": 79,
        "energy_provenance": {
          "source": "fdc_sr_legacy",
          "record_id": "172963",
          "source_nutrient_id": "1008",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "is_preferred": true,
        "matched_name": "Chicken breast, oven-roasted, fat-free, sliced",
        "matched_lang": "en"
      },
      "… 1 more"
    ],
    "ranking": "generic foods, then dishes, then branded products; each by full-text relevance (bm25)"
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "1",
    "dataset": "food",
    "dataset_version": "1.0.0",
    "dataset_built_at": "2026-10-10T17:56:11Z",
    "data_status": "released",
    "sources": [
      {
        "id": "ah102",
        "name": "USDA Agriculture Handbook No. 102, Food Yields Summarized by Different Stages of Preparation (1975)",
        "url": "https://www.ars.usda.gov/ARSUserFiles/80400525/Data/Classics/ah102.pdf",
        "licence": "U.S. Government work (USDA), public domain in the United States",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "1975 (scanned PDF, ARS Classics)",
        "attribution": "Matthews RH, Garrison YJ. Food Yields Summarized by Different Stages of Preparation. Agriculture Handbook No. 102, USDA, 1975."
      },
      {
        "id": "ciqual",
        "name": "ANSES-CIQUAL French food composition table 2025 (English edition)",
        "url": "https://ciqual.anses.fr/cms/sites/default/files/inline-files/Table%20Ciqual%202025_ENG_2025_11_03.xlsx",
        "licence": "Licence Ouverte / Open Licence (Etalab). Reuse allowed, including commercial, on condition that the data are not altered, their meaning is not distorted, the source and version date are cited, and no …",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "2025 (file dated 2025-11-03)",
        "attribution": "Anses. 2025. Ciqual French food composition table."
      },
      "… 8 more"
    ],
    "provenance_note": "Every value carries provenance (source, id or URL, retrieval date; method and confidence where an AI judged). Calculations list their inputs and method.",
    "disclaimer": "Nutrition reference data. Not medical or dietary advice.",
    "usage": "…"
  }
}

GET`/v1/food/foods/{id}`

Get a food by id. All nutrients per 100 g (or per 100 ml for products labelled per ml) with per-value provenance (source dataset, record id, source nutrient id, retrieval date, method), names in five languages with how each was made, portions with gram weights and their sources, and flags. Dishes include their recipe, cooking-yield tier and the computation trail.

Cost: 1 unit. MCP tool: food_get.

Parameters
Name	In	Type	Required	Notes
`id`	path	string	yes	fdc:<FDC id>, ciqual:<code>, gtin:<GTIN-14> or dish:<id>

Example

curl -s "https://api.nutrientgraph.com/v1/food/foods/fdc%3A171477" \
  -H "X-API-Key: $API_KEY"

Response (200, real output of the API on the current data; long arrays trimmed)

{
  "data": {
    "id": "fdc:171477",
    "type": "generic",
    "names": [
      {
        "lang": "en",
        "name": "Chicken, broilers or fryers, breast, meat only, cooked, roasted",
        "method": "source",
        "source": "fdc_sr_legacy"
      },
      {
        "lang": "de",
        "name": "Brat- oder Backhähnchen, Brust, nur Fleisch, gegart, gebraten",
        "method": "machine_translation",
        "translated_from": "en",
        "check_status": "confirmed",
        "model": "Claude Opus 5.5 (claude-opus-5-5)"
      },
      "… 3 more"
    ],
    "group": "poultry",
    "basis": "100 g",
    "nutrients": {
      "alcohol_g": 0,
      "calcium_mg": 15,
      "carbohydrate_g": 0,
      "cholesterol_mg": 85,
      "energy_kcal": 165,
      "energy_kj": 690,
      "fat_g": 3.57,
      "fiber_g": 0,
      "iron_mg": 1.04,
      "mufa_g": 1.24,
      "potassium_mg": 256,
      "protein_g": 31.02,
      "pufa_g": 0.77,
      "saturated_fat_g": 1.01,
      "sodium_mg": 74,
      "sugars_g": 0,
      "water_g": 65.26,
      "added_sugars_g": null,
      "trans_fat_g": null
    },
    "units": {
      "alcohol_g": "g",
      "calcium_mg": "mg",
      "carbohydrate_g": "g",
      "cholesterol_mg": "mg",
      "energy_kcal": "kcal",
      "energy_kj": "kJ",
      "fat_g": "g",
      "fiber_g": "g",
      "iron_mg": "mg",
      "mufa_g": "g",
      "potassium_mg": "mg",
      "protein_g": "g",
      "pufa_g": "g",
      "saturated_fat_g": "g",
      "sodium_mg": "mg",
      "sugars_g": "g",
      "water_g": "g",
      "added_sugars_g": "g",
      "trans_fat_g": "g"
    },
    "portions": [
      {
        "description": "1 cup, chopped or diced",
        "grams": 140,
        "source": "fdc_sr_legacy food_portion id=88817"
      },
      {
        "description": "1 unit (yield from 1 lb ready-to-cook chicken)",
        "grams": 52,
        "source": "fdc_sr_legacy food_portion id=88818"
      },
      "… 1 more"
    ],
    "primary_portion": {
      "description": "1 cup, chopped or diced",
      "grams": 140,
      "source": "fdc_sr_legacy food_portion id=88817"
    },
    "source": {
      "dataset": "fdc_sr_legacy",
      "name": "USDA FoodData Central - SR Legacy",
      "version": "2018-04",
      "record_id": "171477",
      "code": "5064",
      "code_type": "ndb_number",
      "url": "https://fdc.nal.usda.gov/food-details/171477/nutrients",
      "retrieved": "2026-10-10",
      "licence": "CC0 1.0 Universal (USDA FoodData Central)",
      "publication_date": "2019-04-01"
    },
    "mapping": {
      "type": "source",
      "sources": [
        {
          "dataset": "fdc_sr_legacy",
          "id": "171477"
        }
      ]
    },
    "description": {
      "name_en": "Chicken, broilers or fryers, breast, meat only, cooked, roasted",
      "base_name_en": "Chicken, broilers or fryers, breast, meat only",
      "source_category": "Poultry Products",
      "food_group_method": "SR food category map",
      "preparation_state": "cooked",
      "preparation_methods": [
        "roasted",
        "cooked"
      ],
      "processing": []
    },
    "carb_definition": "by_difference_incl_fibre",
    "cluster": {
      "cluster_id": "fdc:171477",
      "is_preferred": true,
      "relation": "preferred",
      "note": "USDA crosswalk cluster: records of the same food from different USDA analyses; the preferred one is the catalogue entry"
    },
    "aliases": [],
    "missing": [
      "added_sugars_g",
      "trans_fat_g"
    ],
    "flags": [],
    "warnings": [],
    "provenance": {
      "nutrients": {
        "alcohol_g": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1018",
          "source_nutrient_name": "Alcohol, ethyl",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "calcium_mg": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1087",
          "source_nutrient_name": "Calcium, Ca",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "carbohydrate_g": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1005",
          "source_nutrient_name": "Carbohydrate, by difference",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "cholesterol_mg": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1253",
          "source_nutrient_name": "Cholesterol",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "energy_kcal": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1008",
          "source_nutrient_name": "Energy",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "energy_kj": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1062",
          "source_nutrient_name": "Energy",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "fat_g": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1004",
          "source_nutrient_name": "Total lipid (fat)",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "fiber_g": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1079",
          "source_nutrient_name": "Fiber, total dietary",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "iron_mg": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1089",
          "source_nutrient_name": "Iron, Fe",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "mufa_g": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1292",
          "source_nutrient_name": "Fatty acids, total monounsaturated",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "potassium_mg": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1092",
          "source_nutrient_name": "Potassium, K",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "protein_g": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1003",
          "source_nutrient_name": "Protein",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "pufa_g": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1293",
          "source_nutrient_name": "Fatty acids, total polyunsaturated",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "saturated_fat_g": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1258",
          "source_nutrient_name": "Fatty acids, total saturated",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "sodium_mg": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1093",
          "source_nutrient_name": "Sodium, Na",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "sugars_g": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "2000",
          "source_nutrient_name": "Total Sugars",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        },
        "water_g": {
          "dataset": "fdc_sr_legacy",
          "id": "171477",
          "source_nutrient_id": "1051",
          "source_nutrient_name": "Water",
          "retrieved": "2026-10-10",
          "method": "copied from source"
        }
      }
    }
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "1",
    "dataset": "food",
    "dataset_version": "1.0.0",
    "dataset_built_at": "2026-10-10T17:56:11Z",
    "data_status": "released",
    "sources": [
      {
        "id": "ah102",
        "name": "USDA Agriculture Handbook No. 102, Food Yields Summarized by Different Stages of Preparation (1975)",
        "url": "https://www.ars.usda.gov/ARSUserFiles/80400525/Data/Classics/ah102.pdf",
        "licence": "U.S. Government work (USDA), public domain in the United States",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "1975 (scanned PDF, ARS Classics)",
        "attribution": "Matthews RH, Garrison YJ. Food Yields Summarized by Different Stages of Preparation. Agriculture Handbook No. 102, USDA, 1975."
      },
      {
        "id": "ciqual",
        "name": "ANSES-CIQUAL French food composition table 2025 (English edition)",
        "url": "https://ciqual.anses.fr/cms/sites/default/files/inline-files/Table%20Ciqual%202025_ENG_2025_11_03.xlsx",
        "licence": "Licence Ouverte / Open Licence (Etalab). Reuse allowed, including commercial, on condition that the data are not altered, their meaning is not distorted, the source and version date are cited, and no …",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "2025 (file dated 2025-11-03)",
        "attribution": "Anses. 2025. Ciqual French food composition table."
      },
      "… 8 more"
    ],
    "provenance_note": "Every value carries provenance (source, id or URL, retrieval date; method and confidence where an AI judged). Calculations list their inputs and method.",
    "disclaimer": "Nutrition reference data. Not medical or dietary advice.",
    "usage": "…"
  }
}

GET`/v1/food/barcode/{gtin}`

Look up a packaged product by barcode. GTIN-8, UPC-A (12), EAN-13 or GTIN-14. The check digit is validated and the code normalised to GTIN-14. Returns the product from USDA Branded Foods with the FDC records behind it.

Cost: 1 unit. MCP tool: food_barcode.

Parameters
Name	In	Type	Required	Notes
`gtin`	path	string	yes

Example

curl -s "https://api.nutrientgraph.com/v1/food/barcode/016000228986" \
  -H "X-API-Key: $API_KEY"

Response (200, real output of the API on the current data; long arrays trimmed)

{
  "data": {
    "gtin14": "00016000228986",
    "product": {
      "id": "gtin:00016000228986",
      "type": "branded",
      "names": [
        {
          "lang": "en",
          "name": "Dunkaroos Cinnamon Graham Cookie Vanilla Frosting 12 Count",
          "source": "fdc_branded description (as labelled)"
        }
      ],
      "group": "sweets_desserts",
      "gtin": "00016000228986",
      "gtin_published": "00016000228986",
      "gtin_derivation": "as published",
      "brand": "GENERAL MILLS SALES INC.",
      "brand_name": "DunkAroos",
      "subbrand_name": "",
      "market": "United States",
      "category": "Biscuits/Cookies",
      "ingredients": "Vanilla Frosting with Rainbow Chips: Sugar, High Fructose Corn Syrup, Palm Oil, Corn Starch, Water, Salt, Monoglycerides, Polysorbate 60, Nonfat Dry Milk, Whey Powder, Sodium Acid Pyrophosphate, Sodiu…",
      "basis": "100 g",
      "nutrients": {
        "energy_kcal": 429,
        "energy_kj": null,
        "protein_g": 2.38,
        "fat_g": 14.29,
        "carbohydrate_g": 71.43,
        "fiber_g": 2.4,
        "sugars_g": 45.24,
        "saturated_fat_g": 7.14,
        "sodium_mg": 357,
        "water_g": null,
        "alcohol_g": null,
        "added_sugars_g": 42.9,
        "trans_fat_g": 0,
        "mufa_g": null,
        "pufa_g": null,
        "cholesterol_mg": 0,
        "potassium_mg": 0,
        "calcium_mg": 0,
        "iron_mg": 1.19
      },
      "units": {
        "energy_kcal": "kcal",
        "energy_kj": "kJ",
        "protein_g": "g",
        "fat_g": "g",
        "carbohydrate_g": "g",
        "fiber_g": "g",
        "sugars_g": "g",
        "saturated_fat_g": "g",
        "sodium_mg": "mg",
        "water_g": "g",
        "alcohol_g": "g",
        "added_sugars_g": "g",
        "trans_fat_g": "g",
        "mufa_g": "g",
        "pufa_g": "g",
        "cholesterol_mg": "mg",
        "potassium_mg": "mg",
        "calcium_mg": "mg",
        "iron_mg": "mg"
      },
      "portions": [
        {
          "description": "1 serving (1 tray with frosting) = 42 GRM",
          "grams": 42,
          "source": "fdc_branded 2739214 label serving size"
        }
      ],
      "primary_portion": {
        "description": "1 serving (1 tray with frosting) = 42 GRM",
        "grams": 42,
        "source": "fdc_branded 2739214 label serving size"
      },
      "package_weight": "18 ONZ",
      "dates": {
        "available": "2025-07-24",
        "modified": "2025-06-20",
        "publication": "2025-07-24",
        "discontinued": ""
      },
      "source": {
        "dataset": "fdc_branded",
        "record_id": "2739214",
        "url": "https://fdc.nal.usda.gov/food-details/2739214/nutrients",
        "retrieved": "2026-10-10",
        "data_source": "GDSN",
        "selection": "top_ranked",
        "n_records": 2,
        "source_records": [
          {
            "fdc_id": "2739214",
            "rank": 1,
            "role": "canonical",
            "data_source": "GDSN",
            "available_date": "2025-07-24",
            "discontinued_date": "",
            "failed_checks": []
          },
          {
            "fdc_id": "2734636",
            "rank": 2,
            "role": "superseded",
            "data_source": "GDSN",
            "available_date": "2025-06-19",
            "discontinued_date": "",
            "failed_checks": []
          }
        ]
      },
      "mapping": {
        "type": "source",
        "sources": [
          {
            "dataset": "fdc_branded",
            "id": "2739214"
          }
        ]
      },
      "missing": [
        "energy_kj",
        "water_g",
        "… 3 more"
      ],
      "flags": [],
      "provenance": {
        "nutrients": {
          "energy_kcal": {
            "dataset": "fdc_branded",
            "id": "2739214",
            "source_nutrient_id": "1008",
            "retrieved": "2026-10-10",
            "method": "copied from source (per 100 g or 100 ml as the label basis)"
          },
          "protein_g": {
            "dataset": "fdc_branded",
            "id": "2739214",
            "source_nutrient_id": "1003",
            "retrieved": "2026-10-10",
            "method": "copied from source (per 100 g or 100 ml as the label basis)"
          },
          "fat_g": {
            "dataset": "fdc_branded",
            "id": "2739214",
            "source_nutrient_id": "1004",
            "retrieved": "2026-10-10",
            "method": "copied from source (per 100 g or 100 ml as the label basis)"
          },
          "carbohydrate_g": {
            "dataset": "fdc_branded",
            "id": "2739214",
            "source_nutrient_id": "1005",
            "retrieved": "2026-10-10",
            "method": "copied from source (per 100 g or 100 ml as the label basis)"
          },
          "fiber_g": {
            "dataset": "fdc_branded",
            "id": "2739214",
            "source_nutrient_id": "1079",
            "retrieved": "2026-10-10",
            "method": "copied from source (per 100 g or 100 ml as the label basis)"
          },
          "sugars_g": {
            "dataset": "fdc_branded",
            "id": "2739214",
            "source_nutrient_id": "2000",
            "retrieved": "2026-10-10",
            "method": "copied from source (per 100 g or 100 ml as the label basis)"
          },
          "saturated_fat_g": {
            "dataset": "fdc_branded",
            "id": "2739214",
            "source_nutrient_id": "1258",
            "retrieved": "2026-10-10",
            "method": "copied from source (per 100 g or 100 ml as the label basis)"
          },
          "sodium_mg": {
            "dataset": "fdc_branded",
            "id": "2739214",
            "source_nutrient_id": "1093",
            "retrieved": "2026-10-10",
            "method": "copied from source (per 100 g or 100 ml as the label basis)"
          },
          "…": "6 more fields"
        }
      }
    }
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "1",
    "dataset": "food",
    "dataset_version": "1.0.0",
    "dataset_built_at": "2026-10-10T17:56:11Z",
    "data_status": "released",
    "sources": [
      {
        "id": "ah102",
        "name": "USDA Agriculture Handbook No. 102, Food Yields Summarized by Different Stages of Preparation (1975)",
        "url": "https://www.ars.usda.gov/ARSUserFiles/80400525/Data/Classics/ah102.pdf",
        "licence": "U.S. Government work (USDA), public domain in the United States",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "1975 (scanned PDF, ARS Classics)",
        "attribution": "Matthews RH, Garrison YJ. Food Yields Summarized by Different Stages of Preparation. Agriculture Handbook No. 102, USDA, 1975."
      },
      {
        "id": "ciqual",
        "name": "ANSES-CIQUAL French food composition table 2025 (English edition)",
        "url": "https://ciqual.anses.fr/cms/sites/default/files/inline-files/Table%20Ciqual%202025_ENG_2025_11_03.xlsx",
        "licence": "Licence Ouverte / Open Licence (Etalab). Reuse allowed, including commercial, on condition that the data are not altered, their meaning is not distorted, the source and version date are cited, and no …",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "2025 (file dated 2025-11-03)",
        "attribution": "Anses. 2025. Ciqual French food composition table."
      },
      "… 8 more"
    ],
    "provenance_note": "Every value carries provenance (source, id or URL, retrieval date; method and confidence where an AI judged). Calculations list their inputs and method.",
    "disclaimer": "Nutrition reference data. Not medical or dietary advice.",
    "usage": "…"
  }
}

GET`/v1/food/foods/{id}/nutrients`

Nutrients for a portion. Scales per-100 g values to a portion: give grams, or a portion (index or description from the food's portions) and a quantity. Missing values stay null. Products labelled per 100 ml are refused (density unknown).

Cost: 1 unit. MCP tool: food_nutrients_for_portion.

Parameters
Name	In	Type	Required	Notes
`id`	path	string	yes	fdc:<FDC id>, ciqual:<code>, gtin:<GTIN-14> or dish:<id>
`grams`	query	number	no
`portion`	query	string	no	Portion index (0-based) or description
`quantity`	query	number	no	Default 1.

Example

curl -s "https://api.nutrientgraph.com/v1/food/foods/fdc%3A171477/nutrients?portion=0&quantity=1" \
  -H "X-API-Key: $API_KEY"

Response (200, real output of the API on the current data; long arrays trimmed)

{
  "data": {
    "food_id": "fdc:171477",
    "name": "Chicken, broilers or fryers, breast, meat only, cooked, roasted",
    "basis": "100 g",
    "portion": {
      "description": "1 cup, chopped or diced",
      "grams": 140,
      "source": "fdc_sr_legacy food_portion id=88817"
    },
    "quantity": 1,
    "grams_total": 140,
    "nutrients": {
      "alcohol_g": {
        "value": 0,
        "unit": "g",
        "per_100g": 0
      },
      "calcium_mg": {
        "value": 21,
        "unit": "mg",
        "per_100g": 15
      },
      "carbohydrate_g": {
        "value": 0,
        "unit": "g",
        "per_100g": 0
      },
      "cholesterol_mg": {
        "value": 119,
        "unit": "mg",
        "per_100g": 85
      },
      "energy_kcal": {
        "value": 231,
        "unit": "kcal",
        "per_100g": 165
      },
      "energy_kj": {
        "value": 966,
        "unit": "kJ",
        "per_100g": 690
      },
      "fat_g": {
        "value": 4.998,
        "unit": "g",
        "per_100g": 3.57
      },
      "fiber_g": {
        "value": 0,
        "unit": "g",
        "per_100g": 0
      },
      "iron_mg": {
        "value": 1.456,
        "unit": "mg",
        "per_100g": 1.04
      },
      "mufa_g": {
        "value": 1.736,
        "unit": "g",
        "per_100g": 1.24
      },
      "potassium_mg": {
        "value": 358.4,
        "unit": "mg",
        "per_100g": 256
      },
      "protein_g": {
        "value": 43.428,
        "unit": "g",
        "per_100g": 31.02
      },
      "pufa_g": {
        "value": 1.078,
        "unit": "g",
        "per_100g": 0.77
      },
      "saturated_fat_g": {
        "value": 1.414,
        "unit": "g",
        "per_100g": 1.01
      },
      "sodium_mg": {
        "value": 103.6,
        "unit": "mg",
        "per_100g": 74
      },
      "sugars_g": {
        "value": 0,
        "unit": "g",
        "per_100g": 0
      },
      "water_g": {
        "value": 91.364,
        "unit": "g",
        "per_100g": 65.26
      },
      "added_sugars_g": {
        "value": null,
        "unit": "g",
        "per_100g": null
      },
      "trans_fat_g": {
        "value": null,
        "unit": "g",
        "per_100g": null
      }
    },
    "missing": [
      "added_sugars_g",
      "trans_fat_g"
    ],
    "method": "value = per-100 g source value x grams / 100 (code; missing values stay null)",
    "provenance": {
      "food": {
        "nutrients": {
          "alcohol_g": {
            "dataset": "fdc_sr_legacy",
            "id": "171477",
            "source_nutrient_id": "1018",
            "source_nutrient_name": "Alcohol, ethyl",
            "retrieved": "2026-10-10",
            "method": "copied from source"
          },
          "calcium_mg": {
            "dataset": "fdc_sr_legacy",
            "id": "171477",
            "source_nutrient_id": "1087",
            "source_nutrient_name": "Calcium, Ca",
            "retrieved": "2026-10-10",
            "method": "copied from source"
          },
          "carbohydrate_g": {
            "dataset": "fdc_sr_legacy",
            "id": "171477",
            "source_nutrient_id": "1005",
            "source_nutrient_name": "Carbohydrate, by difference",
            "retrieved": "2026-10-10",
            "method": "copied from source"
          },
          "cholesterol_mg": {
            "dataset": "fdc_sr_legacy",
            "id": "171477",
            "source_nutrient_id": "1253",
            "source_nutrient_name": "Cholesterol",
            "retrieved": "2026-10-10",
            "method": "copied from source"
          },
          "energy_kcal": {
            "dataset": "fdc_sr_legacy",
            "id": "171477",
            "source_nutrient_id": "1008",
            "source_nutrient_name": "Energy",
            "retrieved": "2026-10-10",
            "method": "copied from source"
          },
          "energy_kj": {
            "dataset": "fdc_sr_legacy",
            "id": "171477",
            "source_nutrient_id": "1062",
            "source_nutrient_name": "Energy",
            "retrieved": "2026-10-10",
            "method": "copied from source"
          },
          "fat_g": {
            "dataset": "fdc_sr_legacy",
            "id": "171477",
            "source_nutrient_id": "1004",
            "source_nutrient_name": "Total lipid (fat)",
            "retrieved": "2026-10-10",
            "method": "copied from source"
          },
          "fiber_g": {
            "dataset": "fdc_sr_legacy",
            "id": "171477",
            "source_nutrient_id": "1079",
            "source_nutrient_name": "Fiber, total dietary",
            "retrieved": "2026-10-10",
            "method": "copied from source"
          },
          "…": "9 more fields"
        }
      },
      "portion_source": "fdc_sr_legacy food_portion id=88817"
    }
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "1",
    "dataset": "food",
    "dataset_version": "1.0.0",
    "dataset_built_at": "2026-10-10T17:56:11Z",
    "data_status": "released",
    "sources": [
      {
        "id": "ah102",
        "name": "USDA Agriculture Handbook No. 102, Food Yields Summarized by Different Stages of Preparation (1975)",
        "url": "https://www.ars.usda.gov/ARSUserFiles/80400525/Data/Classics/ah102.pdf",
        "licence": "U.S. Government work (USDA), public domain in the United States",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "1975 (scanned PDF, ARS Classics)",
        "attribution": "Matthews RH, Garrison YJ. Food Yields Summarized by Different Stages of Preparation. Agriculture Handbook No. 102, USDA, 1975."
      },
      {
        "id": "ciqual",
        "name": "ANSES-CIQUAL French food composition table 2025 (English edition)",
        "url": "https://ciqual.anses.fr/cms/sites/default/files/inline-files/Table%20Ciqual%202025_ENG_2025_11_03.xlsx",
        "licence": "Licence Ouverte / Open Licence (Etalab). Reuse allowed, including commercial, on condition that the data are not altered, their meaning is not distorted, the source and version date are cited, and no …",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "2025 (file dated 2025-11-03)",
        "attribution": "Anses. 2025. Ciqual French food composition table."
      },
      "… 8 more"
    ],
    "provenance_note": "Every value carries provenance (source, id or URL, retrieval date; method and confidence where an AI judged). Calculations list their inputs and method.",
    "disclaimer": "Nutrition reference data. Not medical or dietary advice.",
    "usage": "…"
  }
}

POST`/v1/food/recipe`

Calculate a recipe. Nutrients per 100 g as eaten (and per serving) of a recipe from ingredient foods and grams, with the food dataset's recipe engine (the code that computed its 150 dishes). Weight changes come only from cited sources you name: a cooked record of the same food (convert.to_cooked, by dry-matter balance), FNDDS moisture change, a USDA meat/poultry yield row, a verified AH-102 row, or an SR refuse portion; no yield is ever assumed (T6) and the result's tier says which kind was used. A nutrient missing for an ingredient is taken from a USDA crosswalk-linked record of the same food, else the result is null with a lower bound (never zero, T7). Nutrient numbers in the request are rejected.

Cost: 1 unit per 5 ingredients (minimum 1). MCP tool: food_recipe_calculate.

Request body schema

{
  "type": "object",
  "required": [
    "cooked",
    "ingredients"
  ],
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string",
      "maxLength": 200
    },
    "cooked": {
      "type": "boolean",
      "description": "false: no heat step (tier T0); true: cooked (T1-T3 from the references used)"
    },
    "servings": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "ingredients": {
      "type": "array",
      "minItems": 1,
      "maxItems": 60,
      "items": {
        "type": "object",
        "required": [
          "food"
        ],
        "additionalProperties": false,
        "properties": {
          "food": {
            "type": "string",
            "pattern": "^(fdc|ciqual|gtin|fdc_branded):[0-9A-Za-z]{1,20}$",
            "description": "Ingredient food: fdc:<FDC id>, ciqual:<code>, gtin:<GTIN-14> (per-100 g products only) or fdc_branded:<FDC id>"
          },
          "grams": {
            "type": "number",
            "exclusiveMinimum": 0,
            "maximum": 100000,
            "description": "Grams as written in the recipe (raw weight)"
          },
          "label": {
            "type": "string",
            "maxLength": 200
          },
          "convert": {
            "type": "object",
            "additionalProperties": false,
            "description": "Enter the ingredient as a cooked record of the same food",
            "properties": {
              "to_cooked": {
                "type": "string",
                "pattern": "^(fdc|ciqual|gtin|fdc_branded):[0-9A-Za-z]{1,20}$",
                "description": "Ingredient food: fdc:<FDC id>, ciqual:<code>, gtin:<GTIN-14> (per-100 g products only) or fdc_branded:<FDC id>"
              },
              "yield": {
                "type": "object",
                "additionalProperties": false,
                "description": "Weight raw -> cooked from a cited yield (else dry-matter balance between the two records)",
                "properties": {
                  "fndds_moisture": {
                    "type": "integer",
                    "description": "FNDDS 2021-2023 food code: its recipe moisture change"
                  },
                  "meat_yield_row": {
                    "type": "integer",
                    "description": "Row of the USDA Table of Cooking Yields for Meat and Poultry"
                  },
                  "fat": {
                    "type": "string",
                    "enum": [
                      "drained",
                      "kept"
                    ],
                    "description": "meat_yield_row: 'drained' removes the fat change (only when the method drains fat)"
                  },
                  "ah102_item": {
                    "type": "integer",
                    "description": "Verified row of USDA Agriculture Handbook 102"
                  },
                  "evaporate_all_water": {
                    "type": "boolean",
                    "description": "All water of the ingredient cooks off (flagged as estimated, T3)"
                  },
                  "match": {
                    "type": "string",
                    "enum": [
                      "same_food",
                      "analog"
                    ],
                    "description": "analog: the yield of a similar food (flags the result T3 estimated)"
                  },
                  "sr_refuse_portion": {
                    "type": "object",
                    "required": [
                      "food",
                      "seq"
                    ],
                    "additionalProperties": false,
                    "properties": {
                      "food": {
                        "type": "string",
                        "pattern": "^(fdc|ciqual|gtin|fdc_branded):[0-9A-Za-z]{1,20}$",
                        "description": "Ingredient food: fdc:<FDC id>, ciqual:<code>, gtin:<GTIN-14> (per-100 g products only) or fdc_branded:<FDC id>"
                      },
                      "seq": {
                        "type": "integer",
                        "minimum": 1
                      }
                    },
                    "description": "SR 'yield from 1 lb raw' portion"
                  }
                }
              },
              "edible_ah102": {
                "type": "integer",
                "description": "AH-102 item for the edible portion (refuse removed)"
              },
              "match": {
                "type": "string",
                "enum": [
                  "same_food",
                  "analog"
                ]
              }
            }
          },
          "cook": {
            "type": "object",
            "additionalProperties": false,
            "description": "One cited weight-change source (from GET /v1/food/cooking-yields): exactly one of fndds_moisture, meat_yield_row, ah102_item, evaporate_all_water",
            "properties": {
              "fndds_moisture": {
                "type": "integer",
                "description": "FNDDS 2021-2023 food code: its recipe moisture change"
              },
              "meat_yield_row": {
                "type": "integer",
                "description": "Row of the USDA Table of Cooking Yields for Meat and Poultry"
              },
              "fat": {
                "type": "string",
                "enum": [
                  "drained",
                  "kept"
                ],
                "description": "meat_yield_row: 'drained' removes the fat change (only when the method drains fat)"
              },
              "ah102_item": {
                "type": "integer",
                "description": "Verified row of USDA Agriculture Handbook 102"
              },
              "evaporate_all_water": {
                "type": "boolean",
                "description": "All water of the ingredient cooks off (flagged as estimated, T3)"
              },
              "match": {
                "type": "string",
                "enum": [
                  "same_food",
                  "analog"
                ],
                "description": "analog: the yield of a similar food (flags the result T3 estimated)"
              }
            }
          },
          "retention_code": {
            "type": "integer",
            "minimum": 1,
            "description": "USDA Release 6 nutrient retention code (minerals; alcohol with its energy)"
          },
          "grams_rule": {
            "type": "object",
            "required": [
              "fndds_ratio"
            ],
            "additionalProperties": false,
            "description": "Grams from an FNDDS recipe ratio (e.g. water absorbed per gram of rice)",
            "properties": {
              "fndds_ratio": {
                "type": "object",
                "required": [
                  "food_code",
                  "ingredient_codes",
                  "per_codes",
                  "of"
                ],
                "additionalProperties": false,
                "properties": {
                  "food_code": {
                    "type": "integer"
                  },
                  "ingredient_codes": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "per_codes": {
                    "type": "array",
                    "items": {
                      "type": "integer"
                    }
                  },
                  "of": {
                    "type": "array",
                    "items": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "description": "0-based indexes of earlier ingredients the ratio applies to"
                  }
                }
              },
              "match": {
                "type": "string",
                "enum": [
                  "same_food",
                  "analog"
                ]
              }
            }
          }
        }
      }
    },
    "hydrate": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "object",
        "required": [
          "members",
          "like"
        ],
        "additionalProperties": false,
        "properties": {
          "members": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0
            }
          },
          "like": {
            "type": "string",
            "pattern": "^(fdc|ciqual|gtin|fdc_branded):[0-9A-Za-z]{1,20}$",
            "description": "Ingredient food: fdc:<FDC id>, ciqual:<code>, gtin:<GTIN-14> (per-100 g products only) or fdc_branded:<FDC id>"
          },
          "match": {
            "type": "string",
            "enum": [
              "same_food",
              "analog"
            ]
          }
        }
      },
      "description": "Bring a group of ingredients to the water content of a cooked record (e.g. a dough)"
    },
    "group_cook": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "object",
        "required": [
          "members",
          "cook"
        ],
        "additionalProperties": false,
        "properties": {
          "members": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0
            }
          },
          "cook": {
            "type": "object",
            "additionalProperties": false,
            "description": "One cited weight-change source (from GET /v1/food/cooking-yields): exactly one of fndds_moisture, meat_yield_row, ah102_item, evaporate_all_water",
            "properties": {
              "fndds_moisture": {
                "type": "integer",
                "description": "FNDDS 2021-2023 food code: its recipe moisture change"
              },
              "meat_yield_row": {
                "type": "integer",
                "description": "Row of the USDA Table of Cooking Yields for Meat and Poultry"
              },
              "fat": {
                "type": "string",
                "enum": [
                  "drained",
                  "kept"
                ],
                "description": "meat_yield_row: 'drained' removes the fat change (only when the method drains fat)"
              },
              "ah102_item": {
                "type": "integer",
                "description": "Verified row of USDA Agriculture Handbook 102"
              },
              "evaporate_all_water": {
                "type": "boolean",
                "description": "All water of the ingredient cooks off (flagged as estimated, T3)"
              },
              "match": {
                "type": "string",
                "enum": [
                  "same_food",
                  "analog"
                ],
                "description": "analog: the yield of a similar food (flags the result T3 estimated)"
              }
            }
          }
        }
      },
      "description": "Weight change of a group of ingredients (e.g. a sauce reduced)"
    },
    "dish_cook": {
      "type": "object",
      "additionalProperties": false,
      "description": "One cited weight-change source (from GET /v1/food/cooking-yields): exactly one of fndds_moisture, meat_yield_row, ah102_item, evaporate_all_water",
      "properties": {
        "fndds_moisture": {
          "type": "integer",
          "description": "FNDDS 2021-2023 food code: its recipe moisture change"
        },
        "meat_yield_row": {
          "type": "integer",
          "description": "Row of the USDA Table of Cooking Yields for Meat and Poultry"
        },
        "fat": {
          "type": "string",
          "enum": [
            "drained",
            "kept"
          ],
          "description": "meat_yield_row: 'drained' removes the fat change (only when the method drains fat)"
        },
        "ah102_item": {
          "type": "integer",
          "description": "Verified row of USDA Agriculture Handbook 102"
        },
        "evaporate_all_water": {
          "type": "boolean",
          "description": "All water of the ingredient cooks off (flagged as estimated, T3)"
        },
        "match": {
          "type": "string",
          "enum": [
            "same_food",
            "analog"
          ],
          "description": "analog: the yield of a similar food (flags the result T3 estimated)"
        }
      }
    },
    "uncovered_heat_steps": {
      "type": "array",
      "maxItems": 10,
      "items": {
        "type": "string",
        "maxLength": 200
      },
      "description": "Heat steps you know of that have no USDA yield (flags the result T3)"
    },
    "retention_code": {
      "type": "integer",
      "minimum": 1
    }
  }
}

Example

curl -s "https://api.nutrientgraph.com/v1/food/recipe" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"scrambled eggs on buttered toast","cooked":true,"servings":1,"ingredients":[{"food":"fdc:748967","grams":100,"label":"egg, whole, raw (2 large)"},{"food":"fdc:171265","grams":30,"label":"whole milk"},{"food":"fdc:173410","grams":10,"label":"butter, salted"},{"food":"fdc:2707598","grams":60,"label":"white sandwich bread (2 slices), toasted","convert":{"to_cooked":"fdc:2707599"}},{"food":"fdc:173468","grams":1,"label":"table salt"}],"dish_cook":{"fndds_moisture":32130020,"match":"same_food"}}'

Response (200, real output of the API on the current data; long arrays trimmed)

{
  "data": {
    "name": "scrambled eggs on buttered toast",
    "basis": "per 100 g as eaten (after the cooking steps given)",
    "per_100g": {
      "energy_kcal": {
        "value": 203.465,
        "unit": "kcal"
      },
      "protein_g": {
        "value": 9.758,
        "unit": "g"
      },
      "fat_g": {
        "value": 10.8371,
        "unit": "g"
      },
      "carbohydrate_g": {
        "value": 16.3231,
        "unit": "g"
      },
      "fiber_g": {
        "value": 0.6978,
        "unit": "g"
      },
      "sugars_g": {
        "value": 2.5184,
        "unit": "g"
      },
      "saturated_fat_g": {
        "value": 4.8,
        "unit": "g"
      },
      "sodium_mg": {
        "value": 441.7432,
        "unit": "mg"
      },
      "energy_kj": {
        "value": null,
        "unit": "kJ",
        "lower_bound": 507.7212,
        "missing_weight_share_pct": 29.85,
        "missing_from": [
          4
        ]
      },
      "water_g": {
        "value": 61.2872,
        "unit": "g"
      },
      "alcohol_g": {
        "value": 0,
        "unit": "g"
      },
      "added_sugars_g": {
        "value": null,
        "unit": "g",
        "lower_bound": 0,
        "missing_weight_share_pct": 100,
        "missing_from": [
          1,
          2,
          "… 3 more"
        ]
      },
      "trans_fat_g": {
        "value": null,
        "unit": "g",
        "lower_bound": 0.2042,
        "missing_weight_share_pct": 29.85,
        "missing_from": [
          4
        ]
      },
      "mufa_g": {
        "value": 3.275,
        "unit": "g"
      },
      "pufa_g": {
        "value": 1.6896,
        "unit": "g"
      },
      "cholesterol_mg": {
        "value": 222.6488,
        "unit": "mg"
      },
      "potassium_mg": {
        "value": 125.0071,
        "unit": "mg"
      },
      "calcium_mg": {
        "value": 107.9813,
        "unit": "mg"
      },
      "iron_mg": {
        "value": 1.8911,
        "unit": "mg"
      }
    },
    "per_serving": {
      "servings": 1,
      "grams": 195.6,
      "nutrients": {
        "energy_kcal": 397.9755,
        "protein_g": 19.0865,
        "fat_g": 21.1972,
        "carbohydrate_g": 31.9279,
        "fiber_g": 1.365,
        "sugars_g": 4.926,
        "saturated_fat_g": 9.3888,
        "sodium_mg": 864.0453,
        "energy_kj": null,
        "water_g": 119.8772,
        "alcohol_g": 0,
        "added_sugars_g": null,
        "trans_fat_g": null,
        "mufa_g": 6.4059,
        "pufa_g": 3.3048,
        "cholesterol_mg": 435.4989,
        "potassium_mg": 244.5127,
        "calcium_mg": 211.2103,
        "iron_mg": 3.699
      },
      "method": "per-100 g value x serving grams / 100, serving grams = final weight / servings (code)"
    },
    "weights": {
      "raw_g": 201,
      "after_ingredient_steps_g": 195.599,
      "final_g": 195.599,
      "dish_weight_change": "FNDDS 32130020 'Egg omelet or scrambled egg, made with butter' moisture change +0.0%: 195.6 g -> 195.6 g [code]"
    },
    "yield_tier": "T2_usda_yield",
    "flags": [],
    "carb_definition": "by_difference_incl_fibre",
    "ingredients": [
      {
        "seq": 1,
        "label": "egg, whole, raw (2 large)",
        "food": "fdc:748967",
        "food_id": "fdc:748967",
        "food_name": "Eggs, Grade A, Large, egg whole",
        "recipe_grams": 100,
        "grams_entered": 100,
        "weight_after_cooking_g": 100
      },
      {
        "seq": 2,
        "label": "whole milk",
        "food": "fdc:171265",
        "food_id": "fdc:171265",
        "food_name": "Milk, whole, 3.25% milkfat, with added vitamin D",
        "recipe_grams": 30,
        "grams_entered": 30,
        "weight_after_cooking_g": 30
      },
      "… 3 more"
    ],
    "nutrient_provenance": {
      "energy_kcal": {},
      "protein_g": {},
      "fat_g": {},
      "carbohydrate_g": {},
      "fiber_g": {},
      "sugars_g": {},
      "saturated_fat_g": {},
      "sodium_mg": {},
      "energy_kj": {
        "missing_from": [
          4
        ],
        "rule": "not computed: a value is missing for ingredient(s) [4] and no linked record has it (never counted as zero)",
        "lower_bound": 507.7212,
        "lower_bound_rule": "sum of the known ingredient contributions per 100 g (nutrients are never negative, so the true value is at least this)",
        "missing_weight_share_pct": 29.85
      },
      "water_g": {},
      "alcohol_g": {
        "filled": [
          {
            "ingredient": 1,
            "source": "fdc_sr_legacy:171287",
            "filled_from": "fdc:171287",
            "rule": "missing in fdc:748967; value of USDA crosswalk-linked record fdc:171287 (same food)"
          }
        ]
      },
      "added_sugars_g": {
        "missing_from": [
          1,
          2,
          "… 3 more"
        ],
        "rule": "not computed: a value is missing for ingredient(s) [1, 2, 3, 4, 5] and no linked record has it (never counted as zero)",
        "lower_bound": 0,
        "lower_bound_rule": "sum of the known ingredient contributions per 100 g (nutrients are never negative, so the true value is at least this)",
        "missing_weight_share_pct": 100
      },
      "trans_fat_g": {
        "missing_from": [
          4
        ],
        "rule": "not computed: a value is missing for ingredient(s) [4] and no linked record has it (never counted as zero)",
        "lower_bound": 0.2042,
        "lower_bound_rule": "sum of the known ingredient contributions per 100 g (nutrients are never negative, so the true value is at least this)",
        "missing_weight_share_pct": 29.85,
        "filled": [
          {
            "ingredient": 1,
            "source": "fdc_sr_legacy:171287",
            "filled_from": "fdc:171287",
            "rule": "missing in fdc:748967; value of USDA crosswalk-linked record fdc:171287 (same food)"
          },
          {
            "ingredient": 2,
            "source": "fdc_foundation:746782",
            "filled_from": "fdc:746782",
            "rule": "missing in fdc:171265; value of USDA crosswalk-linked record fdc:746782 (same food)"
          }
        ]
      },
      "mufa_g": {},
      "pufa_g": {},
      "cholesterol_mg": {},
      "potassium_mg": {},
      "calcium_mg": {},
      "iron_mg": {}
    },
    "yield_references": [
      {
        "kind": "to_cooked",
        "match": "same_food"
      },
      {
        "kind": "fndds",
        "match": "same_food"
      }
    ],
    "method": "USDA recipe method: ingredient source values x grams / 100, weight changes only from cited yield sources, divided by the final weight (code; port of datasets/food/pipeline/recipe_engine.py)",
    "policy": {
      "missing_values": "never zero (T7): filled from a USDA crosswalk-linked record of the same food if one reports it (flagged), else null with a lower bound",
      "censored_values": "CIQUAL '< x' uses the middle bound x/2 (flagged)",
      "cooking_yield": "never assumed (T6): tier T0 not cooked, T1 cooked records, T2 USDA yields, T3 estimated (flagged)"
    },
    "note": "Values are estimates for the recipe as written; T3 (estimated yield) results carry larger uncertainty. Not dietary advice."
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "1",
    "dataset": "food",
    "dataset_version": "1.0.0",
    "dataset_built_at": "2026-10-10T17:56:11Z",
    "data_status": "released",
    "sources": [
      {
        "id": "ah102",
        "name": "USDA Agriculture Handbook No. 102, Food Yields Summarized by Different Stages of Preparation (1975)",
        "url": "https://www.ars.usda.gov/ARSUserFiles/80400525/Data/Classics/ah102.pdf",
        "licence": "U.S. Government work (USDA), public domain in the United States",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "1975 (scanned PDF, ARS Classics)",
        "attribution": "Matthews RH, Garrison YJ. Food Yields Summarized by Different Stages of Preparation. Agriculture Handbook No. 102, USDA, 1975."
      },
      {
        "id": "ciqual",
        "name": "ANSES-CIQUAL French food composition table 2025 (English edition)",
        "url": "https://ciqual.anses.fr/cms/sites/default/files/inline-files/Table%20Ciqual%202025_ENG_2025_11_03.xlsx",
        "licence": "Licence Ouverte / Open Licence (Etalab). Reuse allowed, including commercial, on condition that the data are not altered, their meaning is not distorted, the source and version date are cited, and no …",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "2025 (file dated 2025-11-03)",
        "attribution": "Anses. 2025. Ciqual French food composition table."
      },
      "… 8 more"
    ],
    "provenance_note": "Every value carries provenance (source, id or URL, retrieval date; method and confidence where an AI judged). Calculations list their inputs and method.",
    "disclaimer": "Nutrition reference data. Not medical or dietary advice.",
    "usage": "…"
  }
}

GET`/v1/food/cooking-yields`

Find cooking-yield references. Rows of the USDA Table of Cooking Yields for Meat and Poultry, verified rows of USDA Agriculture Handbook 102 and FNDDS recipe moisture changes, each with the `reference` to use in a recipe.

Cost: 1 unit. MCP tool: food_cooking_yields.

Parameters
Name	In	Type	Required	Notes
`q`	query	string	no
`source`	query	string: meat, ah102, fndds	no
`limit`	query	integer	no	Default 25.

Example

curl -s "https://api.nutrientgraph.com/v1/food/cooking-yields?q=ground+beef&source=meat&limit=3" \
  -H "X-API-Key: $API_KEY"

Response (200, real output of the API on the current data; long arrays trimmed)

{
  "data": {
    "count": 3,
    "rows": [
      {
        "source": "cooking_yields_meat",
        "reference": {
          "meat_yield_row": 23
        },
        "rowno": 23,
        "food_group": "13",
        "ndb": 13494,
        "description": "Beef, ground, high fat (>22%), crumbles",
        "method": "Fried in pan, Sauteed, or Stir-fried",
        "yield_pct": 62,
        "n": 4,
        "sd": 1.6,
        "moisture_change_pct": -25,
        "fat_change_pct": -12.6,
        "year": 2003
      },
      {
        "source": "cooking_yields_meat",
        "reference": {
          "meat_yield_row": 24
        },
        "rowno": 24,
        "food_group": "13",
        "ndb": 13495,
        "description": "Beef, ground, high fat (>22%), loaf",
        "method": "Baked or Roasted, unspecified",
        "yield_pct": 63,
        "n": 4,
        "sd": 0.9,
        "moisture_change_pct": -22.5,
        "fat_change_pct": -12.9,
        "year": 2003
      },
      "… 1 more"
    ],
    "usage": "Use `reference` as cook (or convert.yield / dish_cook) in POST /v1/food/recipe. Meat rows: add fat: 'drained' only when the method drains the fat."
  },
  "meta": {
    "request_id": "req_…",
    "api_version": "1",
    "dataset": "food",
    "dataset_version": "1.0.0",
    "dataset_built_at": "2026-10-10T17:56:11Z",
    "data_status": "released",
    "sources": [
      {
        "id": "ah102",
        "name": "USDA Agriculture Handbook No. 102, Food Yields Summarized by Different Stages of Preparation (1975)",
        "url": "https://www.ars.usda.gov/ARSUserFiles/80400525/Data/Classics/ah102.pdf",
        "licence": "U.S. Government work (USDA), public domain in the United States",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "1975 (scanned PDF, ARS Classics)",
        "attribution": "Matthews RH, Garrison YJ. Food Yields Summarized by Different Stages of Preparation. Agriculture Handbook No. 102, USDA, 1975."
      },
      {
        "id": "ciqual",
        "name": "ANSES-CIQUAL French food composition table 2025 (English edition)",
        "url": "https://ciqual.anses.fr/cms/sites/default/files/inline-files/Table%20Ciqual%202025_ENG_2025_11_03.xlsx",
        "licence": "Licence Ouverte / Open Licence (Etalab). Reuse allowed, including commercial, on condition that the data are not altered, their meaning is not distorted, the source and version date are cited, and no …",
        "commercial_redistribution_ok": true,
        "retrieved": "2026-10-10",
        "version": "2025 (file dated 2025-11-03)",
        "attribution": "Anses. 2025. Ciqual French food composition table."
      },
      "… 8 more"
    ],
    "provenance_note": "Every value carries provenance (source, id or URL, retrieval date; method and confidence where an AI judged). Calculations list their inputs and method.",
    "disclaimer": "Nutrition reference data. Not medical or dietary advice.",
    "usage": "…"
  }
}

API documentation

Getting started

Responses and provenance

Errors and limits

MCP for AI agents

Endpoints

GET/v1/food/search

Example

GET/v1/food/foods/{id}

Example

GET/v1/food/barcode/{gtin}

Example

GET/v1/food/foods/{id}/nutrients

Example

POST/v1/food/recipe

Example

GET/v1/food/cooking-yields

Example

GET`/v1/food/search`

GET`/v1/food/foods/{id}`

GET`/v1/food/barcode/{gtin}`

GET`/v1/food/foods/{id}/nutrients`

POST`/v1/food/recipe`

GET`/v1/food/cooking-yields`