Skip to main content

An official website of the United States government

FoodData Central API Guide

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.

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

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.

Response Fields
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.
Food Fields
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"}'

-X POST

https://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.

Request Parameters
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”

https://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.