OrbTop

USDA FDC Recipe Nutrition Enricher

DEVELOPER TOOLSOTHER
Try on Apify

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
Try on Apify