Overview
The FoodData Central API provides REST access to FoodData Central (FDC). It is intended primarily to assist application developers wishing to incorporate nutrient data into their applications or websites.
To take full advantage of the API, developers should familiarize themselves with the database by reading the database documentation available via links on Data Type Documentation. This documentation provides the detailed definitions and descriptions needed to understand the data elements referenced in the API documentation.
What's Available
The API provides two endpoints: the Food Search endpoint, which returns foods that match desired search criteria, and the Food Details endpoint, which returns details on a particular food.
Gaining Access
Anyone may access and use the API. However, a data.gov API key must be incorporated into each API request. Sign up to obtain a key.
Rate Limits
FoodData Central currently limits the number of API requests to a default rate of 3,600 requests per hour per IP address, as this is adequate for most applications. Exceeding this limit will cause the API key to be temporarily blocked for 1 hour. More detailed information on rate limits may be found at api.data.gov. Contact FoodData Central if a higher request rate setting is needed.
Licensing
USDA food composition data are in the public domain and they are not copyrighted. No permission is needed for their use. USDA would appreciate it if developers would list FoodData Central as the source of the data. And, when possible, USDA would like to see the product that uses the data or be notified of their use. The suggested citation is:
U.S. Department of Agriculture, Agricultural Research Service. FoodData Central, 2019. fdc.nal.usda.gov.
Note: Release numbers and years change as new versions are released. For more information, please see Download Data.
Examples and Further Details
Select the links below for more detailed information on how to formulate API requests and understand responses.
- Food Search endpoint – lists foods that match desired search criteria
- Food Details endpoint – provides details on a particular food
What is the Food Search endpoint
The Food Search endpoint lists foods that match desired search criteria. Search operators are supported.
How it Works
The Food Search endpoint requires at least one request parameter.
Request Parameters
| Parameter | Description | Example |
|---|---|---|
api_key |
Required. Must be a data.gov registered API key. | |
generalSearchInput |
Search query (general text). | "generalSearchInput":"raw +broccoli" |
includeDataTypes |
Specific data types to include in search. | "includeDataTypes":{"Survey (FNDDS)":true,"Foundation":true,"Branded":false} |
ingredients |
The list of ingredients (as it appears on the product label). | "ingredients":"sugar -syrup" |
brandOwner |
Brand owner for the food. | "brandOwner":"usa" |
requireAllWords |
When true, the search will only return foods that contain all of the words that were entered in the search field. | "requireAllWords":"true" |
pageNumber |
The page of results to return. | "pageNumber":"1" |
sortField |
The name of the field by which to sort. Possible sorting options: lowercaseDescription.keyword, dataType.keyword, publishedDate, fdcId. |
"sortField":"publishedDate" |
sortDirection |
The direction of the sorting, either "asc" or "desc". | "sortDirection":"asc" |
Response Elements
The Food Search endpoint returns a list of foods that match the search criteria.
| Field | Description |
|---|---|
foodSearchCriteria |
A copy of the criteria that were used in the search. See Request Parameters above. |
totalHits |
The total number of foods found matching the search criteria. |
currentPage |
The current page of results being returned. |
totalPages |
The total number of pages found matching the search criteria. |
foods |
The list of foods found matching the search criteria. See Food Fields below. |
| Field | Description |
|---|---|
fdcId |
Unique ID of the food. |
description |
The description of the food. |
scientificName |
The scientific name of the food. |
commonNames |
Any other common names for the food. |
additionalDescriptions |
Any additional descriptions of the food. |
dataType |
The type of the food data. |
foodCode |
Any A unique ID identifying the food within FNDDS. |
gtinUpc |
GTIN or UPC code identifying the food. |
ndbNumber |
Unique number assigned for foundation foods. |
publishedDate |
Date the item was published to FDC. |
brandOwner |
Brand owner for the food. |
ingredients |
The list of ingredients (as it appears on the product label). |
allHighlightFields |
Fields that were found matching the criteria. |
score |
Relative score indicating how well the food matches the search criteria. |
Example call to Food Search endpoint:
curl -H "Content-Type:application/json"
-d '{"generalSearchInput":"Cheddar cheese"}'
DEMO_KEY@api.nal.usda.gov/fdc/v1/search
What is the Food Details endpoint
The Food Details endpoint provides all available details on a particular food.
How it Works
The Food Details endpoint requires one request parameter in addition to the api_key: a FoodData Central ID. To find a valid FDC ID use the Food Search endpoint.
| Parameter | Description |
|---|---|
| API key | Required. Must be a data.gov registered API key. |
| FDC ID | Required. Unique identifier for the food. |
Response Elements
The Food Details endpoint returns all available details on a particular food. Hundreds of different data elements can be returned. For further details, see the Dictionary tab of the FoodData Central Download & API Field Descriptions (XLSX - 50K). Note the following caveats:
- Data elements in the Download & API Field Descriptions use the snake case naming convention (lower_case_separated_by_underscores) more commonly used in databases, while the API uses the lower camel case convention (allWordsButFirstAreCapitalized) typically used in web services.
- The API Location column on the Dictionary tab of the Download & API Field Descriptions lists the location of any element whose location is not obvious.
- The API returns a smaller number of data elements than does the downloaded dataset, because API data are returned as a structured JSON document.
Example call to Food Details endpoint:
curl -H “Content-Type:application/json”
DEMO_KEY@api.nal.usda.gov/fdc/v1/#####
The number at the end of the URL must be a valid FoodData Central ID. To find a valid FoodData Central ID use the Food Search endpoint.