FoodData Central (FDC) API in Python#
By Sebastian Shirk and Avery Fernandez
The FoodData Central (FDC) API provides programmatic access to the FDC database, which is maintained by the U.S. Department of Agriculture (USDA). The database contains a wide range of information about food products, including nutrient content, ingredients, and serving sizes.
Please see the following resources for more information on API usage:
Documentation
Terms
Data Reuse
NOTE: The FoodData Central API limits requests to a maximum of 1,000 per hour.
These recipe examples were tested on May 7, 2025.
“U.S. Department of Agriculture, Agricultural Research Service. FoodData Central, 2019. fdc.nal.usda.gov.”
“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).”
Setup#
Import Libraries#
The following external libraries need to be installed into your enviornment to run the code examples in this tutorial:
We import the libraries used in this tutorial below:
import requests
import polars as pl
from pprint import pprint
import os
from dotenv import load_dotenv
Import API Key#
An API key is required to access the FoodData Central API. You can sign up for one at the FoodData Central API Key Signup page.
We keep our API key in a separate file, a .env file, and use the dotenv library to access it. If you use this method, create a file named .env in the same directory as this notebook and add the following line to it:
FDC_API_KEY=PUT_YOUR_API_KEY_HERE
load_dotenv()
try:
API_KEY = os.environ["FDC_API_KEY"]
except KeyError:
print("API key not found. Please set 'FDC_API_KEY' in your .env file.")
else:
print("Environment and API key successfully loaded.")
Environment and API key successfully loaded.
1. Searching for Different Brands of Food and Obtaining Their Data#
BASE_URL = 'https://api.nal.usda.gov/fdc/v1/'
endpoint = 'foods/search'
# Change the query to search for different foods and the pageSize to get more or fewer results
params = {
"query": "cheese",
"dataType": "Branded",
"pageSize": 2,
"pageNumber": 0,
"sortBy": "dataType.keyword",
"sortOrder": "asc",
"brandOwner": "",
"api_key": API_KEY,
}
# Used to get all the foods of that category in the database
try:
response = requests.get(f"{BASE_URL}{endpoint}", params=params)
# Raise an error for bad responses
response.raise_for_status()
data = response.json()
results = data.get('foods', [])
# Print the first result in a readable format
pprint(results[0], depth=1)
except requests.exceptions.RequestException as e:
print(f"Error fetching data: {e}")
results = []
{'allHighlightFields': '',
'brandName': 'FERNDALE FARMSTEAD',
'brandOwner': 'Ferndale Farmstead LLC',
'dataSource': 'LI',
'dataType': 'Branded',
'description': 'CHEESE',
'fdcId': 1943515,
'finalFoodInputFoods': [],
'foodAttributeTypes': [],
'foodAttributes': [],
'foodCategory': 'Cheese',
'foodMeasures': [],
'foodNutrients': [...],
'foodVersionIds': [],
'gtinUpc': '853910006170',
'householdServingFullText': '1 ONZ',
'ingredients': 'MILK, SALT, CULTURES, ENZYMES.',
'marketCountry': 'United States',
'microbes': [],
'modifiedDate': '2018-08-11',
'packageWeight': '9.5 oz/269 g',
'publishedDate': '2021-07-29',
'score': 662.3066,
'servingSize': 28.399999618530273,
'servingSizeUnit': 'g',
'tradeChannels': [...]}
# Used to look up each individual food to get more details
if len(results) > 0:
# Get the FDC ID of the first food item
fdc_id = results[0]['fdcId']
endpoint = f"food/{fdc_id}"
params = {
"api_key": API_KEY,
}
try:
response = requests.get(f"{BASE_URL}{endpoint}", params=params)
# Raise an error for bad responses
response.raise_for_status()
# Print the food details in a readable format
pprint(response.json(), depth=1)
except requests.exceptions.RequestException as e:
print(f"Error fetching food details: {e}")
{'availableDate': '8/11/2018',
'brandName': 'FERNDALE FARMSTEAD',
'brandOwner': 'Ferndale Farmstead LLC',
'brandedFoodCategory': 'Cheese',
'dataSource': 'LI',
'dataType': 'Branded',
'description': 'CHEESE',
'discontinuedDate': '',
'fdcId': 1943515,
'foodAttributes': [...],
'foodClass': 'Branded',
'foodComponents': [],
'foodNutrients': [...],
'foodPortions': [],
'foodUpdateLog': [...],
'gtinUpc': '853910006170',
'householdServingFullText': '1 ONZ',
'ingredients': 'MILK, SALT, CULTURES, ENZYMES.',
'labelNutrients': {},
'marketCountry': 'United States',
'modifiedDate': '8/11/2018',
'packageWeight': '9.5 oz/269 g',
'publicationDate': '7/29/2021',
'servingSizeUnit': 'g'}
2. Creating a Nutrient Table#
The function below creates a table of nutrients for a given food item.
food_data = []
nutrient_data = []
# Loop through the food items and extract the relevant data
for food in results:
fdc_id = food['fdcId']
endpoint = f"food/{fdc_id}"
params = {
"api_key": API_KEY,
}
try:
response = requests.get(f"{BASE_URL}{endpoint}", params=params)
# Raise an error for bad responses
response.raise_for_status()
food_details = response.json()
except requests.exceptions.RequestException as e:
print(f"Error fetching food details: {e}")
continue
# Extract the relevant data from the food item
food_data.append([
fdc_id,
food_details.get("brandName", ""),
food_details.get("brandOwner", ""),
food_details.get("marketCountry", ""),
food_details.get("description", ""),
food_details.get("brandedFoodCategory", ""),
""
])
# Extract the nutrient data
serving_size = food_details.get("servingSize", "")
serving_size_unit = food_details.get("servingSizeUnit", "")
nutrient_data.append([
fdc_id,
"Serving Size",
f"{serving_size} {serving_size_unit}"
])
# Loop through the food's nutrients and extract the relevant data
for nutrient in food_details.get("foodNutrients", []):
nutrient_serving_size = nutrient.get("amount", "")
nutrient_serving_size_unit = nutrient.get("unitName", "")
nutrient_data.append([
fdc_id,
nutrient.get("nutrient", {}).get("name", ""),
f"{nutrient_serving_size} {nutrient_serving_size_unit}",
])
food_df = pl.DataFrame(
food_data,
schema=["FDCID", "Brand Name", "Brand Owner", "Market Country", "Description",
"Food Category", "Calculated from value per serving size measure"],
orient="row"
)
food_df
shape: (2, 7)
| FDCID | Brand Name | Brand Owner | Market Country | Description | Food Category | Calculated from value per serving size measure |
|---|---|---|---|---|---|---|
| i64 | str | str | str | str | str | str |
| 1943515 | "FERNDALE FARMSTEAD" | "Ferndale Farmstead LLC" | "United States" | "CHEESE" | "Cheese" | "" |
| 2083541 | "S.J. FALBO" | "American Pride Food Corp." | "United States" | "CHEESE" | "Cheese" | "" |
nutrient_df = pl.DataFrame(
nutrient_data,
schema=["FDCID", "Nutrient Name", "Nutrient Amount"],
orient="row"
)
nutrient_df
shape: (30, 3)
| FDCID | Nutrient Name | Nutrient Amount |
|---|---|---|
| i64 | str | str |
| 1943515 | "Serving Size" | " g" |
| 1943515 | "Vitamin A, IU" | "176.0 " |
| 1943515 | "Fiber, total dietary" | "0.0 " |
| 1943515 | "Total Sugars" | "0.0 " |
| 1943515 | "Sodium, Na" | "599.0 " |
| … | … | … |
| 2083541 | "Fatty acids, total trans" | "0.0 " |
| 2083541 | "Energy" | "500.0 " |
| 2083541 | "Cholesterol" | "100.0 " |
| 2083541 | "Protein" | "60.0 " |
| 2083541 | "Vitamin C, total ascorbic acid" | "0.0 " |
nutrient_pivot_df = nutrient_df.pivot(
index="FDCID",
on="Nutrient Name",
values="Nutrient Amount"
)
nutrient_pivot_df
shape: (2, 16)
| FDCID | Serving Size | Vitamin A, IU | Fiber, total dietary | Total Sugars | Sodium, Na | Total lipid (fat) | Carbohydrate, by difference | Fatty acids, total trans | Vitamin C, total ascorbic acid | Iron, Fe | Energy | Fatty acids, total saturated | Calcium, Ca | Protein | Cholesterol |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| i64 | str | str | str | str | str | str | str | str | str | str | str | str | str | str | str |
| 1943515 | " g" | "176.0 " | "0.0 " | "0.0 " | "599.0 " | "24.65 " | "2.46 " | "0.0 " | "0.0 " | "0.0 " | "331.0 " | "17.61 " | "0.0 " | "21.13 " | "53.0 " |
| 2083541 | "5.0 g" | "2000.0 " | "0.0 " | "0.0 " | "2000.0 " | "40.0 " | "40.0 " | "0.0 " | "0.0 " | "0.0 " | "500.0 " | "30.0 " | "1200.0 " | "60.0 " | "100.0 " |
combined_df = food_df.join(nutrient_pivot_df, on="FDCID", how="left")
pl.Config.set_fmt_str_lengths(1000)
pl.Config.set_tbl_cols(8)
# Uncomment the following line to see all columns
# pl.Config.set_tbl_cols(100)
pl.Config.set_tbl_rows(100)
print(combined_df)
shape: (2, 22)
┌─────────┬────────────┬────────────┬────────────┬───┬───────────┬───────────┬─────────┬───────────┐
│ FDCID ┆ Brand Name ┆ Brand ┆ Market ┆ … ┆ Fatty ┆ Calcium, ┆ Protein ┆ Cholester │
│ --- ┆ --- ┆ Owner ┆ Country ┆ ┆ acids, ┆ Ca ┆ --- ┆ ol │
│ i64 ┆ str ┆ --- ┆ --- ┆ ┆ total ┆ --- ┆ str ┆ --- │
│ ┆ ┆ str ┆ str ┆ ┆ saturated ┆ str ┆ ┆ str │
│ ┆ ┆ ┆ ┆ ┆ --- ┆ ┆ ┆ │
│ ┆ ┆ ┆ ┆ ┆ str ┆ ┆ ┆ │
╞═════════╪════════════╪════════════╪════════════╪═══╪═══════════╪═══════════╪═════════╪═══════════╡
│ 1943515 ┆ FERNDALE ┆ Ferndale ┆ United ┆ … ┆ 17.61 ┆ 0.0 ┆ 21.13 ┆ 53.0 │
│ ┆ FARMSTEAD ┆ Farmstead ┆ States ┆ ┆ ┆ ┆ ┆ │
│ ┆ ┆ LLC ┆ ┆ ┆ ┆ ┆ ┆ │
│ 2083541 ┆ S.J. FALBO ┆ American ┆ United ┆ … ┆ 30.0 ┆ 1200.0 ┆ 60.0 ┆ 100.0 │
│ ┆ ┆ Pride Food ┆ States ┆ ┆ ┆ ┆ ┆ │
│ ┆ ┆ Corp. ┆ ┆ ┆ ┆ ┆ ┆ │
└─────────┴────────────┴────────────┴────────────┴───┴───────────┴───────────┴─────────┴───────────┘
3. Creating an Ingredient Table#
The function below will create a table of ingredients for a given food product.
food_data = []
for food in results:
fdc_id = food['fdcId']
endpoint = f"food/{fdc_id}"
params = {
"api_key": API_KEY,
}
try:
response = requests.get(f"{BASE_URL}{endpoint}", params=params)
# Raise an error for bad responses
response.raise_for_status()
food_details = response.json()
except requests.exceptions.RequestException as e:
print(f"Error fetching food details: {e}")
continue
# Extract the relevant data from the food item
food_data.append([
fdc_id,
food_details.get("brandName", ""),
food_details.get("brandOwner", ""),
food_details.get("marketCountry", ""),
food_details.get("description", ""),
food_details.get("brandedFoodCategory", ""),
food_details.get("ingredients", "")
])
food_df = pl.DataFrame(
food_data,
schema=["FDCID", "Brand Name", "Brand Owner", "Market Country",
"Description", "Food Category", "Ingredients"],
orient="row"
)
pl.Config.set_fmt_str_lengths(10000)
pl.Config.set_tbl_cols(100)
pl.Config.set_tbl_rows(100)
print(food_df)
shape: (2, 7)
┌─────────┬────────────┬─────────────────┬─────────┬─────────────┬────────────────┬────────────────┐
│ FDCID ┆ Brand Name ┆ Brand Owner ┆ Market ┆ Description ┆ Food Category ┆ Ingredients │
│ --- ┆ --- ┆ --- ┆ Country ┆ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str ┆ --- ┆ str ┆ str ┆ str │
│ ┆ ┆ ┆ str ┆ ┆ ┆ │
╞═════════╪════════════╪═════════════════╪═════════╪═════════════╪════════════════╪════════════════╡
│ 1943515 ┆ FERNDALE ┆ Ferndale ┆ United ┆ CHEESE ┆ Cheese ┆ MILK, SALT, │
│ ┆ FARMSTEAD ┆ Farmstead LLC ┆ States ┆ ┆ ┆ CULTURES, │
│ ┆ ┆ ┆ ┆ ┆ ┆ ENZYMES. │
│ 2083541 ┆ S.J. FALBO ┆ American Pride ┆ United ┆ CHEESE ┆ Cheese ┆ PARMESAN AND │
│ ┆ ┆ Food Corp. ┆ States ┆ ┆ ┆ ROMANO CHEESE. │
│ ┆ ┆ ┆ ┆ ┆ ┆ MADE FROM │
│ ┆ ┆ ┆ ┆ ┆ ┆ PASTEURIZED │
│ ┆ ┆ ┆ ┆ ┆ ┆ COW'S AND │
│ ┆ ┆ ┆ ┆ ┆ ┆ SHEEP'S MILK, │
│ ┆ ┆ ┆ ┆ ┆ ┆ CULTURE, SALT, │
│ ┆ ┆ ┆ ┆ ┆ ┆ AND ENZYMES. │
│ ┆ ┆ ┆ ┆ ┆ ┆ MICROCELLULOSE │
│ ┆ ┆ ┆ ┆ ┆ ┆ ADDED TO │
│ ┆ ┆ ┆ ┆ ┆ ┆ PREVENT │
│ ┆ ┆ ┆ ┆ ┆ ┆ CAKING. │
└─────────┴────────────┴─────────────────┴─────────┴─────────────┴────────────────┴────────────────┘
4. Specific Food Item Lookup#
These functions will allow us to retrieve information about specific food items from either of the tables we created earlier via the FDCID.
Note that these functions rely on at least one of the tables to be created in the previous steps.
# Retrieve the FDCID of the first food item in the results
if len(results) > 0:
# Index of the food item to retrieve
idx = 0
food = results[idx]
fdc_id = food.get('fdcId')
print(f"FDCID of idx {idx}: {fdc_id}")
# Fetch and display detailed information about the food item
if fdc_id:
try:
response = requests.get(f'{BASE_URL}food/{fdc_id}', params={'api_key': API_KEY})
response.raise_for_status()
pprint(response.json())
except requests.exceptions.RequestException as e:
print(f"Error fetching food details: {e}")
else:
print("No results available to retrieve FDCID.")
FDCID of idx 0: 1943515
{'availableDate': '8/11/2018',
'brandName': 'FERNDALE FARMSTEAD',
'brandOwner': 'Ferndale Farmstead LLC',
'brandedFoodCategory': 'Cheese',
'dataSource': 'LI',
'dataType': 'Branded',
'description': 'CHEESE',
'discontinuedDate': '',
'fdcId': 1943515,
'foodAttributes': [{'id': 2090445,
'name': 'Added Package Weight',
'value': 9}],
'foodClass': 'Branded',
'foodComponents': [],
'foodNutrients': [{'amount': 176.0,
'foodNutrientDerivation': {'code': 'LCCD',
'description': 'Calculated from '
'a daily value '
'percentage per '
'serving size '
'measure',
'id': 75},
'id': 22991118,
'nutrient': {'id': 1104,
'name': 'Vitamin A, IU',
'number': '318',
'rank': 7500,
'unitName': 'IU'},
'type': 'FoodNutrient'},
{'amount': 0.0,
'foodNutrientDerivation': {'code': 'LCCD',
'description': 'Calculated from '
'a daily value '
'percentage per '
'serving size '
'measure',
'id': 75},
'id': 22991114,
'nutrient': {'id': 1079,
'name': 'Fiber, total dietary',
'number': '291',
'rank': 1200,
'unitName': 'g'},
'type': 'FoodNutrient'},
{'amount': 0.0,
'foodNutrientDerivation': {'code': 'LCCS',
'description': 'Calculated from '
'value per '
'serving size '
'measure',
'id': 70},
'id': 22991113,
'nutrient': {'id': 2000,
'name': 'Total Sugars',
'number': '269',
'rank': 1510,
'unitName': 'g'},
'type': 'FoodNutrient'},
{'amount': 599.0,
'foodNutrientDerivation': {'code': 'LCCS',
'description': 'Calculated from '
'value per '
'serving size '
'measure',
'id': 70},
'id': 22991117,
'nutrient': {'id': 1093,
'name': 'Sodium, Na',
'number': '307',
'rank': 5800,
'unitName': 'mg'},
'type': 'FoodNutrient'},
{'amount': 24.65,
'foodNutrientDerivation': {'code': 'LCCS',
'description': 'Calculated from '
'value per '
'serving size '
'measure',
'id': 70},
'id': 22991110,
'nutrient': {'id': 1004,
'name': 'Total lipid (fat)',
'number': '204',
'rank': 800,
'unitName': 'g'},
'type': 'FoodNutrient'},
{'amount': 2.46,
'foodNutrientDerivation': {'code': 'LCCS',
'description': 'Calculated from '
'value per '
'serving size '
'measure',
'id': 70},
'id': 22991111,
'nutrient': {'id': 1005,
'name': 'Carbohydrate, by difference',
'number': '205',
'rank': 1110,
'unitName': 'g'},
'type': 'FoodNutrient'},
{'amount': 0.0,
'foodNutrientDerivation': {'code': 'LCCS',
'description': 'Calculated from '
'value per '
'serving size '
'measure',
'id': 70},
'id': 22991121,
'nutrient': {'id': 1257,
'name': 'Fatty acids, total trans',
'number': '605',
'rank': 15400,
'unitName': 'g'},
'type': 'FoodNutrient'},
{'amount': 0.0,
'foodNutrientDerivation': {'code': 'LCCD',
'description': 'Calculated from '
'a daily value '
'percentage per '
'serving size '
'measure',
'id': 75},
'id': 22991119,
'nutrient': {'id': 1162,
'name': 'Vitamin C, total ascorbic acid',
'number': '401',
'rank': 6300,
'unitName': 'mg'},
'type': 'FoodNutrient'},
{'amount': 0.0,
'foodNutrientDerivation': {'code': 'LCCD',
'description': 'Calculated from '
'a daily value '
'percentage per '
'serving size '
'measure',
'id': 75},
'id': 22991116,
'nutrient': {'id': 1089,
'name': 'Iron, Fe',
'number': '303',
'rank': 5400,
'unitName': 'mg'},
'type': 'FoodNutrient'},
{'amount': 331.0,
'foodNutrientDerivation': {'code': 'LCCS',
'description': 'Calculated from '
'value per '
'serving size '
'measure',
'id': 70},
'id': 22991112,
'nutrient': {'id': 1008,
'name': 'Energy',
'number': '208',
'rank': 300,
'unitName': 'kcal'},
'type': 'FoodNutrient'},
{'amount': 17.61,
'foodNutrientDerivation': {'code': 'LCCS',
'description': 'Calculated from '
'value per '
'serving size '
'measure',
'id': 70},
'id': 22991122,
'nutrient': {'id': 1258,
'name': 'Fatty acids, total saturated',
'number': '606',
'rank': 9700,
'unitName': 'g'},
'type': 'FoodNutrient'},
{'amount': 0.0,
'foodNutrientDerivation': {'code': 'LCCD',
'description': 'Calculated from '
'a daily value '
'percentage per '
'serving size '
'measure',
'id': 75},
'id': 22991115,
'nutrient': {'id': 1087,
'name': 'Calcium, Ca',
'number': '301',
'rank': 5300,
'unitName': 'mg'},
'type': 'FoodNutrient'},
{'amount': 21.13,
'foodNutrientDerivation': {'code': 'LCCS',
'description': 'Calculated from '
'value per '
'serving size '
'measure',
'id': 70},
'id': 22991109,
'nutrient': {'id': 1003,
'name': 'Protein',
'number': '203',
'rank': 600,
'unitName': 'g'},
'type': 'FoodNutrient'},
{'amount': 53.0,
'foodNutrientDerivation': {'code': 'LCCS',
'description': 'Calculated from '
'value per '
'serving size '
'measure',
'id': 70},
'id': 22991120,
'nutrient': {'id': 1253,
'name': 'Cholesterol',
'number': '601',
'rank': 15700,
'unitName': 'mg'},
'type': 'FoodNutrient'}],
'foodPortions': [],
'foodUpdateLog': [{'availableDate': '8/11/2018',
'brandName': 'FERNDALE FARMSTEAD',
'brandOwner': 'Ferndale Farmstead LLC',
'brandedFoodCategory': 'Cheese',
'dataSource': 'LI',
'dataType': 'Branded',
'description': 'CHEESE',
'discontinuedDate': '',
'fdcId': 1943515,
'foodAttributes': [],
'foodClass': 'Branded',
'gtinUpc': '853910006170',
'householdServingFullText': '1 ONZ',
'ingredients': 'MILK, SALT, CULTURES, ENZYMES.',
'marketCountry': 'United States',
'modifiedDate': '8/11/2018',
'packageWeight': '9.5 oz/269 g',
'publicationDate': '7/29/2021',
'servingSizeUnit': 'g'},
{'availableDate': '8/11/2018',
'brandName': 'FERNDALE FARMSTEAD',
'brandOwner': 'Ferndale Farmstead LLC',
'brandedFoodCategory': 'Cheese',
'dataSource': 'LI',
'dataType': 'Branded',
'description': 'CHEESE',
'discontinuedDate': '',
'fdcId': 1808334,
'foodAttributes': [],
'foodClass': 'Branded',
'gtinUpc': '853910006170',
'householdServingFullText': '1 ONZ',
'ingredients': 'MILK, SALT, CULTURES, ENZYMES.',
'marketCountry': 'United States',
'modifiedDate': '8/11/2018',
'packageWeight': '269 g',
'publicationDate': '6/17/2021',
'servingSizeUnit': 'g'}],
'gtinUpc': '853910006170',
'householdServingFullText': '1 ONZ',
'ingredients': 'MILK, SALT, CULTURES, ENZYMES.',
'labelNutrients': {},
'marketCountry': 'United States',
'modifiedDate': '8/11/2018',
'packageWeight': '9.5 oz/269 g',
'publicationDate': '7/29/2021',
'servingSizeUnit': 'g'}