USDA Nutrition Scraper

Searches the USDA FoodData Central database and returns nutrition facts for any food item. Gets calories, protein, fat, carbs, fiber, and the full nutrient breakdown.

What data does it extract?

Field	Description
fdcId	USDA FoodData Central unique ID
description	Food item name (e.g. Chicken breast, raw)
brandName	Brand or manufacturer (for branded items)
ingredients	Ingredient list text
servingSize	Serving size amount
servingSizeUnit	Serving size unit (usually g)
calories	Energy in kcal
protein	Protein in grams
fat	Total fat in grams
carbs	Total carbohydrates in grams
fiber	Dietary fiber in grams
sugar	Total sugars in grams
sodium	Sodium in milligrams
cholesterol	Cholesterol in milligrams
allNutrients	Full array of all nutrients with name, amount, and unit
dataType	USDA dataset: Foundation, SR Legacy, Branded, or Survey
publishedDate	Date the record was published
upc	UPC barcode (for branded products)
searchQuery	The search term that matched this item

Use cases

• Nutrition apps — Build food databases with accurate USDA-sourced macros and micronutrients
• Meal planning tools — Look up calories and macros for recipe ingredients in bulk
• Product comparison — Compare nutrition across branded products by searching specific brands
• Diet research — Pull nutrient data for hundreds of foods to analyze dietary patterns
• Label verification — Cross-check product nutrition labels against USDA reference data

How to use

Search for basic foods:

{
    "searchQueries": ["chicken breast", "brown rice", "avocado"],
    "maxResults": 10
}

Get branded products only:

{
    "searchQueries": ["Cheerios", "Coca Cola"],
    "maxResults": 50,
    "dataType": "Branded"
}

Pull large datasets for research:

{
    "searchQueries": ["salmon"],
    "maxResults": 500,
    "dataType": "Foundation"
}

Input parameters

Parameter	Type	Default	Description
searchQueries	array	[]	Food search terms (e.g. "chicken breast", "oatmeal")
maxResults	integer	100	Max results per query (1-500). Pagination handled automatically
dataType	string	""	Filter by USDA dataset: "" (all), "Foundation", "SR Legacy", "Branded", "Survey"

Output example

{
    "fdcId": 171077,
    "description": "Chicken, broilers or fryers, breast, skinless, boneless, meat only, raw",
    "brandName": null,
    "ingredients": null,
    "servingSize": 100,
    "servingSizeUnit": "g",
    "calories": 120,
    "protein": 22.5,
    "fat": 2.62,
    "carbs": 0,
    "fiber": 0,
    "sugar": 0,
    "sodium": 45,
    "cholesterol": 73,
    "allNutrients": [
        { "name": "Energy", "amount": 120, "unit": "KCAL" },
        { "name": "Protein", "amount": 22.5, "unit": "G" },
        { "name": "Total lipid (fat)", "amount": 2.62, "unit": "G" }
    ],
    "dataType": "Foundation",
    "publishedDate": "2024-10-31",
    "upc": null,
    "searchQuery": "chicken breast"
}

Performance & cost

• Uses the USDA FoodData Central API (free, no key needed — uses the DEMO_KEY)
• Rate limited to ~30 requests/hour with the demo key, so large queries take time
• Pure HTTP requests, no browser — minimal compute cost

FAQ

Do I need a USDA API key? No. The actor uses the free DEMO_KEY which is rate-limited but works without registration. For heavy use, you can get a free key at https://fdc.nal.usda.gov/api-key-signup.html.

What's the difference between the data types? Foundation has lab-analyzed whole foods. SR Legacy is the classic USDA reference database. Branded has commercial products with UPC codes. Survey has foods as consumed in dietary surveys.

Why does maxResults cap at 500? The USDA API returns 50 items per page. The actor paginates automatically, but capping at 500 keeps run times reasonable given the rate limits.

Can I search for specific brands? Yes. Use the brand name as your search query (e.g. "Cheerios") and set dataType to "Branded" to filter out generic foods.