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
| Question | Capability | Main option |
|---|---|---|
| Which US foods match a name? | usda-food/search | query |
| What is in one US food? | usda-food/food | fdcId |
| Which US branded product has this barcode? | usda-food/barcode | gtinUpc |
| What is in this packaged product? | openfoodfacts/product | barcode |
| Nutrient amounts for one Canadian food | canadiannutrientfile/nutrient-amounts | food_code |
| Which supplement labels match a keyword? | dsld/products-by-keyword | q |
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:
| Source | Licence 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 File | Published 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
foodfor the detail of onefdcId. - 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
