USDA APIfdc.nal.usda.gov ↗
Access USDA FoodData Central via 6 endpoints. Search foods, retrieve full nutrient profiles, serving sizes, and more across Foundation, Branded, and SR Legacy datasets.
What is the USDA API?
The USDA FoodData Central API provides access to the full FDC database across 6 endpoints, covering Foundation, Branded, SR Legacy, Survey (FNDDS), and Experimental food datasets. Use search_foods to find items by keyword with filtering by data type and brand owner, get_food_nutrients to retrieve pre-categorized macronutrients, vitamins, minerals, and lipids by FDC ID, or get_food_details for the complete nutrient and measurement record for any single food item.
curl -X GET 'https://api.parse.bot/scraper/f47af225-4ebf-4150-8fd9-c2db987ee74e/search_foods?page=1&query=apple&sort_by=description&data_types=Branded&sort_order=asc&brand_owner=TREECRISP+2+GO' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace fdc-nal-usda-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: USDA FoodData Central SDK — bounded, re-runnable."""
from parse_apis.usda_fooddata_central_api import FoodData, SortField, Sort, FoodNotFound
client = FoodData()
# Search for chicken breast foods sorted by description ascending
for food in client.foods.search(query="chicken breast", sort_by=SortField.DESCRIPTION, sort_order=Sort.ASC, limit=3):
print(food.fdc_id, food.description, food.data_type)
# Get full details for a specific food
apple = client.foods.get(fdc_id="1750340")
print(apple.fdc_id, apple.description, apple.serving_size)
# Access structured nutrient profile via sub-resource
profile = apple.nutrients.get()
for name, nutrient in profile.macronutrients.items():
print(nutrient.name, nutrient.amount, nutrient.unit)
# Access serving size info via sub-resource
serving = apple.serving_sizes.get()
print(serving.serving_size, serving.serving_size_unit, serving.household_serving_full_text)
# Batch-fetch multiple foods at once
for food in client.foods.get_batch(fdc_ids="1750340,454004", limit=5):
print(food.fdc_id, food.description)
# Typed error handling for a non-existent food
try:
client.foods.get(fdc_id="9999999999")
except FoodNotFound as exc:
print(f"Food not found: {exc.fdc_id}")
print("exercised: foods.search / foods.get / nutrients.get / serving_sizes.get / foods.get_batch")
Full-text search over the FoodData Central database. Matches query against food descriptions and ingredients. Supports filtering by data type and brand owner, sorting by description/fdcId/publishedDate. Paginates via page number. Each result includes summary nutrient data; use get_food_details for the full record.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number to retrieve |
| queryrequired | string | Search keyword (e.g. 'apple', 'chicken breast') |
| sort_by | string | Field to sort by |
| data_types | string | Comma-separated list of data types to include: Foundation, SR Legacy, Survey (FNDDS), Branded, Experimental. Omitting returns all types. |
| sort_order | string | Sort direction |
| brand_owner | string | Filter by exact brand owner name (e.g. 'TREECRISP 2 GO') |
{
"type": "object",
"fields": {
"foods": "array of food summary objects with fdcId, description, dataType, foodNutrients, and other metadata",
"totalHits": "integer total number of matching foods",
"totalPages": "integer total number of pages",
"currentPage": "integer current page number"
},
"sample": {
"data": {
"foods": [
{
"fdcId": 454004,
"dataType": "Branded",
"brandOwner": "TREECRISP 2 GO",
"description": "APPLE",
"servingSize": 154,
"foodCategory": "Pre-Packaged Fruit & Vegetables",
"foodNutrients": [
{
"value": 0,
"unitName": "MG",
"nutrientName": "Calcium, Ca"
}
],
"servingSizeUnit": "g"
}
],
"totalHits": 26810,
"totalPages": 537,
"currentPage": 1
},
"status": "success"
}
}About the USDA API
Searching and Browsing Foods
The search_foods endpoint accepts a query string and optional filters including data_types (comma-separated values such as Foundation, Branded, SR Legacy), brand_owner for exact brand matching, and sort_by fields like description, fdcId, or publishedDate. Results are paginated and each food summary object in the foods array includes fdcId, description, dataType, and a foodNutrients snapshot. Use list_foods with just a data_types filter to browse all available foods alphabetically without a keyword query.
Retrieving Nutritional Details
get_food_details returns the full record for a single food item identified by fdc_id, including a foodNutrients array with nested nutrient details and analysis data, a foodMeasures array, and the foodType field indicating which FDC dataset the item belongs to. For bulk lookups, get_multiple_foods accepts a comma-separated list of FDC IDs and returns an array of the same full detail objects in one request, which reduces round-trips when building nutrition comparison tools or populating ingredient lists.
Pre-Categorized Nutrient Breakdown
get_food_nutrients returns nutrient values already grouped into five named categories — macronutrients, vitamins, minerals, lipids, and other — each as an object mapping nutrient names to {amount, unit, name}. This is useful when you want a structured nutrient panel without having to classify raw nutrient IDs yourself. get_food_serving_sizes complements this by returning servingSize, servingSizeUnit, householdServingFullText, packageWeight, and a foodMeasures array for a given FDC ID, giving you the context needed to express nutrient amounts per serving rather than per 100g.
The USDA API is a managed, monitored endpoint for fdc.nal.usda.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when fdc.nal.usda.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official fdc.nal.usda.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a nutrition label generator using
get_food_nutrientsmacronutrients, vitamins, and minerals for any FDC ID - Compare nutrient profiles across multiple foods simultaneously with
get_multiple_foods - Filter branded product search results by
brand_ownerto populate a brand-specific food database - Display household serving descriptions and package weights from
get_food_serving_sizesin a recipe app - Paginate through all Foundation or SR Legacy foods via
list_foodsto seed a local nutrition database - Sort food search results by
publishedDatedescending to surface recently added FDC entries - Cross-reference Survey (FNDDS) foods with dietary intake studies by filtering
data_typesinsearch_foods
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does USDA FoodData Central have an official developer API?+
What does `get_food_nutrients` return that `get_food_details` does not?+
get_food_details returns the raw foodNutrients array as it appears in the FDC record, with nested objects containing nutrient metadata and analysis data. get_food_nutrients post-processes that array and groups values into five named buckets — macronutrients, vitamins, minerals, lipids, and other — each mapping nutrient names directly to {amount, unit, name}. This saves you the step of classifying nutrient IDs by hand.Does the API return ingredient lists or allergen information for branded foods?+
description and dataType, but ingredient text and allergen statements are not exposed as dedicated response fields. You can fork this API on Parse and revise it to add an endpoint that extracts those fields from the FDC branded food records.How does pagination work across the search and list endpoints?+
search_foods and list_foods both return totalHits, totalPages, and currentPage alongside the foods array. Pass the page integer parameter to move through result sets. There is no cursor-based pagination — page number is the only navigation mechanism, and results per page follow FDC defaults.Is daily value percentage (% DV) data available from the nutrient endpoints?+
get_food_nutrients returns amount and unit for each nutrient but does not include percent daily value calculations. get_food_details exposes raw nutrient data from FDC without DV percentages. You can fork this API on Parse and revise it to compute % DV values from the returned amounts using standard reference intakes.