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.
Note: The API that was available on the USDA Food Composition Databases Web site is no longer being updated and will be discontinued March 31, 2020. Users are encouraged to begin working with the new FoodData Central API system described on this page. This new API allows users to obtain Standard Reference (SR) Legacy data, provides the most current data from the USDA Global Branded Foods Database, and give users the ability to search for specific foods in Foundation Foods and the Food and Nutrient Database for Dietary Studies (FNDDS) 2019-2020.
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, See Sample Calls for instructions on how to use your key.
Key Responsibility
It is the API Key holder's responsibility to ensure that their key is not made publicly available. Any API keys discovered online, such as those in a code repository, will be deactivated to prevent malicious use.
Rate Limits
FoodData Central currently limits the number of API requests to a default rate of 1,000 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.
How Do I See My Current Usage?
Your can check your current rate limit and usage details by inspecting the X-RateLimit-Limit and X-RateLimit-Remaining HTTP headers that are returned on every API response. For example, if an API has the default hourly limit of 1,000 request, after making 2 requests, you will receive these HTTP headers in the response of the second request:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998
Rate Limit Error Response
If your API key exceeds the rate limits, you will receive a response with an HTTP status code of 429 (Too Many Requests).
Need Higher Limits?
Contact FoodData Central if a higher request rate setting is needed.
Licensing
USDA FoodData Central data are in the public domain and they are not copyrighted. They are published under CC0 1.0 Universal (CC0 1.0)
No permission is needed for their use, but we request that users list FoodData Central as the source of the data, and when possible, notify us of the product that uses the data so we may better track how FDC is being used in the public domain. 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.
API Endpoints
| URL | Verb | Purpose |
|---|---|---|
| /food/{fdcId} | GET | Fetches details for one food item by FDC ID |
| /foods | GET | POST | Fetches details for multiple food items using input FDC IDs |
| /foods/list | GET | POST | Returns a paged list of foods, in the 'abridged' format |
| /foods/search | GET | POST | Returns a list of foods that matched search (query) keywords |
Sample Calls
Note: These calls use DEMO_KEY for the API key, which can be used for initially exploring the API prior to signing up, but has much lower rate limits.
DEMO_KEY Rate Limits
In documentation examples, the special DEMO_KEY api key is used. This API key can be used for initially exploring APIs prior to signing up, but it has much lower rate limits, so you’re encouraged to signup for your own API key if you plan to use the API. The rate limits for the DEMO_KEY are:
Hourly Limit: 30 requests per IP address per hour
Daily Limit: 50 requests per IP address per day
GET REQUEST:
curl https://api.nal.usda.gov/fdc/v1/food/######?api_key=DEMO_KEYThe number (######) in the above sample must be a valid FoodData Central ID.
curl https://api.nal.usda.gov/fdc/v1/foods/list?api_key=DEMO_KEYcurl https://api.nal.usda.gov/fdc/v1/foods/search?api_key=DEMO_KEY&query=Cheddar%20CheesePOST REQUEST:
curl -XPOST -H "Content-Type:application/json" -d '{"pageSize":25}' https://api.nal.usda.gov/fdc/v1/foods/list?api_key=DEMO_KEYcurl -XPOST -H "Content-Type:application/json" -d '{"query":"Cheddar cheese"}' https://api.nal.usda.gov/fdc/v1/foods/search?api_key=DEMO_KEYcurl -XPOST -H "Content-Type:application/json" -d "{\"query\":\"Cheddar cheese\"}" https://api.nal.usda.gov/fdc/v1/foods/search?api_key=DEMO_KEYNote: If using curl on Windows, the body of the POST request (-d option) is enclosed in double quotes (as shown in the above sample).
curl -XPOST -H "Content-Type:application/json" -d '{"query": "Cheddar cheese", "dataType": ["Branded"], "sortBy": "fdcId", "sortOrder": "desc"}' https://api.nal.usda.gov/fdc/v1/foods/search?api_key=DEMO_KEYNote: The "dataType" parameter values need to be specified as an array.
API Spec
The OpenAPI v3 spec for the API provides a complete specification of the API endpoints, including input parameters and output data. It is available in HTML, JSON, or YAML formats.
The spec is also available on SwaggerHub at:
https://app.swaggerhub.com/apis/fdcnal/food-data_central_api/1.0.1