USDA FDC Recipe Nutrition Enricher

Parse any recipe — supply a URL with embedded schema.org/Recipe JSON-LD or a plain-text ingredient list — and get back a full per-serving nutrition panel sourced from the USDA FoodData Central (FDC) database.

Every meal-planning app, recipe site, and food-tech team needs per-serving macros for recipes that don't publish a nutrition block. This actor is the join nobody else on Apify sells: ingredient text → USDA food resolution → gram conversion → nutrient summation → per-serving figures + %DV.

---

What it does

1. Ingests a recipe URL (extracts the recipeIngredient list from JSON-LD) or a direct ingredient array.
2. Parses each ingredient line into quantity, unit, and item name (e.g. "2 cups all-purpose flour" → {qty:2, unit:"cups", item:"all-purpose flour"}).
3. Resolves each item against the USDA FDC search API, preferring Foundation → SR Legacy → Survey (FNDDS) → Branded data types for maximum nutrient coverage.
4. Converts quantities to grams using FDC household-portion data when available, falling back to a standard volume/weight table.
5. Sums 30+ nutrients across all ingredients, divides by serving yield, and computes %DV using the FDA 2020 Daily Value reference values.
6. Returns one output record per recipe with full transparency: resolved ingredient details, unmatched ingredients, match-coverage score, and a list of conversion assumptions.

---

Input

Field	Type	Description
recipeUrl	string (optional)	URL of a page with a schema.org/Recipe JSON-LD block. One of recipeUrl or ingredients must be provided.
ingredients	string[] (optional)	Plain-text ingredient lines (e.g. "1/2 cup unsalted butter"). Overrides any ingredients from recipeUrl.
servings	integer (optional)	Override the recipe's declared yield. Defaults to the value in JSON-LD or 4 if not found.
apiKey	string (optional)	Your own free api.data.gov key (sign up here). If omitted the actor uses the OrbLabs shared key.
maxItems	integer	Maximum enriched recipes to output per run. Default: 5.

Example — inline ingredient list

{
  "ingredients": [
    "2 cups all-purpose flour",
    "1 cup granulated sugar",
    "2 large eggs",
    "1/2 cup unsalted butter",
    "1 tsp vanilla extract",
    "1/4 tsp salt",
    "1/2 cup whole milk"
  ],
  "servings": 12,
  "maxItems": 5
}

Example — recipe URL

{
  "recipeUrl": "https://www.food.com/recipe/definitely-macaroni-salad-24024",
  "maxItems": 5
}

---

Output

Each output record has these fields:

Field	Type	Description
recipe_url	string	Source URL (null for inline ingredient input)
recipe_name	string	Recipe title from JSON-LD
recipe_yield_servings	number	Number of servings used for calculations
ingredients_resolved	JSON string	Array of resolved ingredients: {raw_text, parsed_qty, parsed_unit, parsed_item, matched_fdc_id, fdc_description, match_confidence, grams}
ingredients_unmatched	JSON string	Array of {raw_text, reason} for ingredients that could not be resolved
nutrition_total	JSON string	Summed raw nutrient amounts for the whole recipe
nutrition_per_serving	JSON string	nutrition_total divided by serving yield: {kcal, protein_g, fat_g, sat_fat_g, carbs_g, sugars_g, fiber_g, sodium_mg, cholesterol_mg, ...30 micros}
daily_value_pct	JSON string	Per-serving values as %DV using 2020 FDA reference values
match_coverage_pct	number	Percentage of ingredients successfully matched (quality indicator)
assumptions	JSON string	Human-readable notes about unit conversions and portion assumptions

Sample output record

{
  "recipe_url": null,
  "recipe_name": "",
  "recipe_yield_servings": 12,
  "nutrition_per_serving": "{\"kcal\":252.9,\"protein_g\":6.7,\"fat_g\":10.7,\"carbs_g\":52.9,\"fiber_g\":0,\"sodium_mg\":70.7}",
  "daily_value_pct": "{\"kcal\":12.6,\"protein_g\":13.4,\"fat_g\":13.8,\"carbs_g\":19.2,\"sodium_mg\":3.1}",
  "match_coverage_pct": 100,
  "ingredients_unmatched": "[]"
}

---

Data source

All nutrition data comes from the USDA FoodData Central (FDC) database — the authoritative US government nutrition reference, including Foundation Foods, SR Legacy, Survey (FNDDS), and Branded Foods. Access requires a free api.data.gov key (1,000 requests/hour). The actor provides a shared key for low-volume use; supply your own for production-scale runs.

---

Match coverage and confidence

• match_confidence on each resolved ingredient reflects the FDC data type: Foundation (0.95) → SR Legacy (0.90) → Survey FNDDS (0.80) → Branded (0.65). Use Foundation/SR Legacy matches for the most reliable nutrient figures.
• match_coverage_pct is the share of ingredients that found an FDC match. Values below 70% are flagged with a warning in assumptions. Unmatched ingredients are listed in ingredients_unmatched with the reason (no FDC match, search API error, etc.).
• Gram conversions use FDC household-portion data when available; the fallback volume-weight table covers cups, tablespoons, teaspoons, ounces, and common whole-item units. All fallback conversions are recorded in assumptions.

---

Rate limits

The free api.data.gov key allows 1,000 requests per hour. The actor paces requests at 500 ms intervals, yielding approximately 120 requests per minute — well within the limit for typical recipe enrichment workloads. For bulk batch runs (hundreds of recipes), supply your own api.data.gov key.

---

Use cases

• Enrich community recipes that omit a nutrition block for meal-planning apps
• Build a recipe-to-nutrition dataset for food-tech ML training
• Verify or supplement manually entered nutrition data
• Generate nutrition labels for original recipes before publication