Search USDA Foods
usda_search_foodsSearch USDA FoodData Central foods by keyword. Returns matching foods with FDC IDs and available preview nutrients: protein (1003), fat (1004), carbohydrate (1005), fiber (1079, and 2033 for AOAC 2011.25 total dietary fiber, a separate measure some Foundation foods report beside or instead of 1079), and energy (1008, 1062, 2047, 2048), preserving distinct fiber and energy measures. Missing nutrients are omitted. Use the returned fdcId with usda_get_food for other nutrients or the full profile, or usda_compare_foods for side-by-side comparisons. When dataType is omitted, defaults to SR Legacy (common whole foods with complete profiles), to Branded when brandOwner is set (only Branded records carry one), or to Branded and Survey (FNDDS) when the query is 8–14 digits alone (a UPC/GTIN barcode or an FNDDS food code). A 12–14-digit barcode with a valid check digit also matches the other digit forms FDC stores it in. Set dataType to ["Branded"] for packaged products. Pass brandOwner (e.g. "General Mills") to narrow branded results.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"query": "<query>"
},
"name": "usda_search_foods"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search terms — food name, ingredient, or UPC/GTIN code. Examples: "chicken breast raw", "banana", "02114029705". A food matching any one unqualified word counts, so a multi-word query also returns foods holding only some of its words; set requireAllWords, or prefix each word with +, to require them all. A query of 8–14 digits alone matches a Branded UPC/GTIN code or an 8-digit Survey (FNDDS) food code. A 12-, 13-, or 14-digit code with a valid GTIN check digit (a printed UPC-A or EAN-13) also matches the other digit forms FDC stores that GTIN in: leading zeros added or dropped down to 12 digits, and the 12-digit form without its check digit. Any other code matches only as FDC stores it, leading zeros included. FDC reads Lucene syntax: "quoted phrases", +required and -excluded terms, AND/OR/NOT, wildcards (chick*), fuzzy matches (beeef~), boosts (beef^5), grouping parentheses, field:value, regex terms (/chick.*/), and ranges ([a TO c], {a TO c}). Any other slash, bracket, or brace (1/8, w/o, beef [raw]), any unpaired parenthesis, and every double quote when the query holds an odd number of them are sent as literal characters. | |
| dataType | No | FDC data sources to search. Omitting this defaults to ["SR Legacy"] (common whole foods, complete nutrient profiles), to ["Branded"] when brandOwner is set, or to ["Branded", "Survey (FNDDS)"] when the query is 8–14 digits alone (a UPC/GTIN barcode or an FNDDS food code). Include "Branded" for packaged products. Multiple values allowed. | |
| pageSize | No | Number of results per page. Default 10; a larger value returns at most 200 and says so (a server configured with strict limits rejects more than 200). | |
| brandOwner | No | Filter branded results by brand owner name (e.g. "General Mills", "Kraft"). Matched as one phrase, ignoring case and punctuation: "Kellogg Company" matches owners holding those words in that order. A value containing * or ? is sent as wildcard terms instead, each word matched on its own (e.g. "Kellog*"). For other operators, use field syntax in query (e.g. "+cereal +brandOwner:Kellog*"). Only Branded records carry one, so setting this defaults dataType to ["Branded"] unless dataType is given explicitly. | |
| pageNumber | No | Page number (1-based), counted at the pageSize served. Use with totalPages to paginate. FDC serves only the first 100,000 results of a search, so a page whose pageSize × pageNumber exceeds 100,000 fails with result_window_exceeded, naming the last reachable page, unless it is also past the last page. A page past the last returns empty foods with a notice naming the last reachable page when the query has matches. | |
| foodCategory | No | Filter by USDA food category (e.g. "Poultry Products", "Vegetables and Vegetable Products"). Matched as one phrase, ignoring case and punctuation. A value containing * or ? is sent as wildcard terms instead, each word matched on its own (e.g. "Poult*"); a whole word followed by * can match nothing ("Poultry*" does), so shorten it. For other operators, use field syntax in query (e.g. chicken -foodCategory:"Fast Foods" excludes a category). | |
| requireAllWords | No | Match only foods containing every query word (FDC requireAllWords). Default false: a food matching any one word counts. Explicit OR and "quoted phrases" keep their meaning. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | Present when the call failed. Absent on success. | |
| foods | No | Foods matching the search query. | |
| notice | No | Guidance when the requested pageSize is above FDC's maximum of 200 and pages are served at 200, when the requested page is past the last reachable page, or when more foods match than the first 100,000 FDC serves. | |
| totalHits | No | Total number of foods matching the query across all pages. | |
| totalCount | No | Total foods matching the query across all pages. | |
| totalPages | No | Total number of pages at the pageSize served (the one requested, or 200 when more was requested), as FDC counts them. FDC serves only the first 100,000 results of a search, so when totalHits exceeds 100,000, pages past 100,000 / pageSize (rounded down) are out of reach. | |
| currentPage | No | Current page number (1-based); the requested page for exhausted pages. |