Skip to main content
Tutorial

USDA FoodData Central API in Python and for Agents

Search foods, read nutrients and look up barcodes with USDA FoodData Central, Open Food Facts and the Canadian Nutrient File, all from one API key.

fastcrw
By RecepNovember 16, 20265 min read

By the fastCRW team · Catalogue figures checked 2026-11-05 against GET /v1/data · Verify independently before relying on any figure.

USDA FoodData Central is the US Department of Agriculture's food composition database. Pergamon exposes its search, food detail and barcode lookups as usda-food, next to Open Food Facts, the Canadian Nutrient File and the NIH Dietary Supplement Label Database (DSLD). Every call uses one API key and returns the same response envelope, with the source's licence line and attribution text in provenance.

Search for a food

usda-food/search needs only query. Use pageSize to keep the response small. totalHits counts every match across all pages, not the page size.

curl "https://api.fastcrw.com/v1/data/usda-food/search?query=greek%20yogurt&pageSize=3" \
  -H "Authorization: Bearer $CRW_API_KEY"

Trimmed output from a live call (200, credits_used 1):

{
  "success": true,
  "provider": "usda-food",
  "capability": "search",
  "credits_used": 1,
  "data": {
    "totalHits": 23623,
    "foods": [
      {"fdcId": 2035482, "description": "GREEK YOGURT", "dataType": "Branded", "gtinUpc": "031200037206"},
      {"fdcId": 373595, "description": "GREEK YOGURT", "gtinUpc": "00772914"},
      {"fdcId": 2038865, "description": "GREEK YOGURT", "gtinUpc": "894700010038"}
    ]
  }
}

Branded hits carry a gtinUpc. Keep it, because it is the input to the barcode call below.

Pick the source by question

QuestionCapabilityMain option
Which US foods match a name?usda-food/searchquery
What is in one US food?usda-food/foodfdcId
Which US branded product has this barcode?usda-food/barcodegtinUpc
What is in this packaged product?openfoodfacts/productbarcode
Nutrient amounts for one Canadian foodcanadiannutrientfile/nutrient-amountsfood_code
Which supplement labels match a keyword?dsld/products-by-keywordq

Read one food

usda-food/food takes an fdcId from a search hit. At check time, fdcId=2346396 returned Oats, whole grain, rolled, old fashioned (dataType Foundation) with 33 nutrient rows. The response was 113 KB, so store the fields you need, not the whole body.

curl "https://api.fastcrw.com/v1/data/usda-food/food?fdcId=2346396" \
  -H "Authorization: Bearer $CRW_API_KEY"

In a script, the two steps chain together. The example below searches, takes the first fdcId, and reads that food. It was run live with the Python SDK.

# pip install crw
from crw import CrwClient

client = CrwClient()  # reads CRW_API_KEY
hits = client.get_data("usda-food", "search", {"query": "rolled oats", "pageSize": 2})
print(hits["data"]["totalHits"], "hits")
first = hits["data"]["foods"][0]
print(first["fdcId"], first["description"], first.get("dataType"))
food = client.get_data("usda-food", "food", {"fdcId": str(first["fdcId"])})
print(food["data"]["description"], len(food["data"]["foodNutrients"]), "nutrients")

Real output:

28679 hits
2672932 ROLLED OATS Branded
ROLLED OATS 18 nutrients

Size matters for agents. The Open Food Facts product body is about 155 KB, but the same product call with fields=product_name,brands returned 868 bytes at check time. A USDA detail record for one oat food was 113 KB. Ask for the fields you need and store those, not the whole body.

Look up a barcode in two sources

The two barcode capabilities answer different questions. usda-food/barcode searches USDA's branded foods by GTIN/UPC (the upstream query carries dataType=Branded). openfoodfacts/product reads one product from the community-built Open Food Facts database by barcode. The example below was run live with the Python SDK (crw 0.41.0).

# pip install crw
from crw import CrwClient

client = CrwClient()  # reads CRW_API_KEY

# Open Food Facts: one packaged product by barcode.
off = client.get_data("openfoodfacts", "product", {
    "barcode": "3017620422003",
    "fields": "product_name,brands",  # the full product body is about 155 KB
})
print(off["provenance"]["attributionText"])
print(off["data"]["product"]["product_name"], "|", off["data"]["product"].get("brands"))

# USDA FoodData Central: branded foods by GTIN/UPC.
usda = client.get_data("usda-food", "barcode", {"gtinUpc": "031200037206"})
print(usda["provenance"]["attributionText"])
print("hits:", usda["data"]["totalHits"])
miss = client.get_data("usda-food", "barcode", {"gtinUpc": "041303020466"})
print("hits for an unknown code:", miss["data"]["totalHits"])

Real output:

Source: Open Food Facts (ODbL)
Nutella | Nutella, Ferrero
Source: USDA FoodData Central
hits: 1
hits for an unknown code: 0

A code the database does not hold returns zero hits, not an error. Test the barcode path with a gtinUpc taken from a real search result, as above, so an empty answer tells you something about the data and not about your input.

Canada and supplements

canadiannutrientfile/nutrient-amounts takes a food_code and returned 93 rows of nutrient amounts for food code 2 at check time. dsld/products-by-keyword searches the NIH supplement label database. For q=vitamin d it reported 1,161 hits at check time, and each hit carries the label's full product name.

curl "https://api.fastcrw.com/v1/data/dsld/products-by-keyword?q=vitamin%20d&size=3" \
  -H "Authorization: Bearer $CRW_API_KEY"

Coverage differs by database

USDA's Foundation records describe whole foods such as oats, while its Branded records describe packaged products that carry a GTIN. Open Food Facts is built from contributed product pages, so its coverage of packaged goods follows what contributors have added. Each database has its own coverage, so a miss in one is not a miss in another. When a barcode returns nothing, try the other source before you tell a user the product is unknown.

Nutrition values also differ by source and by record. A Foundation record and a branded record for similar foods can list different nutrient sets. Compare records from the same source, and keep the fdcId or barcode next to every value you show.

Licences differ by source

Each source has its own terms, and the licence line in provenance is the one to show. These are the lines returned on 2026-11-05:

SourceLicence text returned in provenance
USDA FoodData Central"Work of the United States federal government, not subject to copyright in the US (17 U.S.C. 105). Free to use, including commercially, with the agency named as the source."
Open Food Facts"available under the Open Database License (ODbL): commercial use and redistribution are permitted, but a derived database must be shared under the same licence and Open Food Facts must be credited."
NIH DSLD"DSLD data are in the public domain and they are not copyrighted. They are published under CC0 1.0 Universal (CC0 1.0)."
Canadian Nutrient FilePublished by Health Canada under the Open Government Licence, Canada (licence ID ca-ogl-lgo).

Keep attribution_text with the data in your own pipeline, so the source is named wherever a value is shown. You need no USDA key of your own for this server source. Each call costs 1 credit, and a failed call is not billed.

Limits

  • A barcode lookup finds only what the source has entered. Zero hits is a valid answer.
  • Search returns matching foods, not nutrition values. Call food for the detail of one fdcId.
  • Each source's values are what that source publishes. A label on a shelf can differ from a database entry, so check the source before you rely on one number.
  • This is not medical or diet advice. For allergies or medical diets, read the product label and ask a clinician.

Sources

Related: Public data API for AI agents · Free public APIs for AI agents · openFDA and ClinicalTrials.gov API · Pergamon catalogue

Try USDA FoodData Central on Pergamon

FAQ

Frequently asked questions

Which nutrition source should I use?
Use USDA FoodData Central for US foods, the Canadian Nutrient File for Canadian foods, Open Food Facts for packaged products looked up by barcode, and the NIH DSLD for supplement labels. Each source has its own licence, so show the licence line it returns.
Do I need a USDA API key of my own?
No. For these server sources Pergamon makes the call. Each call costs 1 credit, and a failed call is not billed.
Why does my barcode return zero hits?
The code is not in that database. USDA's barcode lookup covers branded foods only. Try a GTIN taken from a real search result, or look the product up in Open Food Facts.

Get Started

Try fastCRW free

Run a live request in the playground — no signup required. Or grab a free API key with 500 credits, earn up to 500 more, no credit card.

Continue exploring

More tutorial posts

View category archive