FoodData Central (FDC) API in Python#
by Sebastian Shirk
FDC API Guide: https://fdc.nal.usda.gov/api-guide.html#bkmk-5
FDC API Documentation: https://app.swaggerhub.com/apis/fdcnal/food-data_central_api/1.0.1
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.
“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).
These reciple examples were tested on August 23, 2024.
Setup#
Import Libraries#
This tutorial will use the following libraries:
import requests
import polars as pl
from pprint import pprint
API Key#
For this API you need an API key. You can get one by signing up for free at https://fdc.nal.usda.gov/api-key-signup.html.
Save your API key in a file called api_key.py and import your key.
from api_key import my_key
Setting variables, parameters, and calling the API#
First, we need to set up the two parameters that we will use to call the API:
The food name you are searching for
The number of results you want to display.
search_url = f'https://api.nal.usda.gov/fdc/v1/foods/search'
query = ""
pageSize = 10
# Change the query to search for different foods and the pageSize to get more or less results
query = 'cheese'
pageSize = '2'
search_params = {
"query": query,
"dataType": "Branded",
"pageSize": pageSize,
"pageNumber": 0,
"sortBy": "dataType.keyword",
"sortOrder": "asc",
"brandOwner": "",
"api_key": my_key,
}
# Used to get all the foods of that category in the database
response = requests.get(search_url, params=search_params)
results = response.json().get('foods', [])
# Used to look up each individual food to get more details
def get_food_details(FDCID, api_key):
url = f'https://api.nal.usda.gov/fdc/v1/food/{FDCID}'
params = {'api_key': api_key}
response = requests.get(url, params=params)
return response.json()
1. Creating a Nutrient Table#
The function below creates a table of nutrients for a given food item.
def get_nutrient_table():
food_data = []
nutrient_data = []
for food in results:
FDCID = food.get('fdcId')
details = get_food_details(FDCID, my_key)
brand_name = details.get('brandName', '')
brand_owner = details.get('brandOwner', '')
marketCountry = details.get('marketCountry', '')
description = details.get('description', '')
food_category = details.get('brandedFoodCategory', '')
serving_size = details.get('servingSize', '')
serving_size_unit = details.get('servingSizeUnit', '')
food_data.append([
FDCID, brand_name, brand_owner, marketCountry, description, food_category, ""
])
nutrient_data.append([
FDCID, "Serving Size", f"{serving_size} {serving_size_unit}"
])
for nutrient in details.get('foodNutrients', []):
nutrient_name = nutrient.get('nutrient', {}).get('name', '')
nutrient_amount = nutrient.get('amount', '')
nutrient_unit = nutrient.get('nutrient', {}).get('unitName', '')
nutrient_data.append([
FDCID, nutrient_name, f"{nutrient_amount} {nutrient_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"
)
nutrient_df = pl.DataFrame(
nutrient_data,
schema=["FDCID", "Nutrient Name", "Nutrient Amount"],
orient="row"
)
nutrient_pivot_df = nutrient_df.pivot(
index="FDCID",
on="Nutrient Name",
values="Nutrient Amount"
)
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)
get_nutrient_table()
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 g ┆ 0.0 mg ┆ 21.13 g ┆ 53.0 mg │
│ ┆ FARMSTEAD ┆ Farmstead ┆ States ┆ ┆ ┆ ┆ ┆ │
│ ┆ ┆ LLC ┆ ┆ ┆ ┆ ┆ ┆ │
│ 2083541 ┆ S.J. FALBO ┆ American ┆ United ┆ … ┆ 30.0 g ┆ 1200.0 mg ┆ 60.0 g ┆ 100.0 mg │
│ ┆ ┆ Pride Food ┆ States ┆ ┆ ┆ ┆ ┆ │
│ ┆ ┆ Corp. ┆ ┆ ┆ ┆ ┆ ┆ │
└─────────┴────────────┴────────────┴────────────┴───┴───────────┴───────────┴─────────┴───────────┘
2. Creating an Ingredient Table#
The function below will create a table of ingredients for a given food product.
def get_ingredients_table():
food_data = []
for food in results:
FDCID = food.get('fdcId')
details = get_food_details(FDCID, my_key)
marketCountry = details.get('marketCountry', '')
brand_name = details.get('brandName', '')
brand_owner = details.get('brandOwner', '')
description = details.get('description', '')
food_category = details.get('brandedFoodCategory', '')
ingredients = details.get('ingredients', '')
food_data.append([
FDCID, brand_name, brand_owner, marketCountry, description, food_category, 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)
get_ingredients_table()
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. │
└─────────┴────────────┴─────────────────┴─────────┴─────────────┴────────────────┴────────────────┘
3. 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.
def get_FDCID(idx):
if 0 <= idx < len(search_params['pageSize']):
food = results[idx]
fdc_id = food.get('fdcId')
print(f"FDCID of idx {idx}: {fdc_id}")
return fdc_id
return None
def get_FDCID_data(FDCID):
if FDCID:
response = requests.get(f'https://api.nal.usda.gov/fdc/v1/food/{FDCID}', params={'api_key': my_key})
pprint(response.json())
get_FDCID_data(get_FDCID(0))
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',
'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',
'ingredients': 'MILK, SALT, CULTURES, ENZYMES.',
'marketCountry': 'United States',
'modifiedDate': '8/11/2018',
'packageWeight': '269 g',
'publicationDate': '6/17/2021',
'servingSizeUnit': 'g'}],
'gtinUpc': '853910006170',
'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'}