USDA Food Data Central (FDC) Python Client

A comprehensive Python library for interacting with the USDA Food Data Central API, designed for easy integration with Django applications and local database caching.

Features

• Complete API coverage for the USDA Food Data Central (FDC) database
• Object-oriented interface for working with food data
• Comprehensive data models for all FDC data types
• Efficient caching mechanisms for Django integration
• Support for searching, filtering, and retrieving detailed nutritional information
• Barcode (gtin_upc) exposed on branded foods, so a barcode lookup can be verified rather than trusted
• Request timeouts on every call, raising FdcTimeoutError instead of hanging
• Conversion utilities for different measurement units
• Batch operations for efficient API usage
• Command-line interface for quick data access
• Nutrient analysis with dietary reference intake comparisons
• Recipe analysis with ingredient parsing and nutritional calculations
• Visualization tools for nutrient data
• Detailed documentation and examples

Installation

pip install usda-fdc

Or install from source:

git clone https://github.com/mcgarrah/usda_fdc_python.git
cd usda_fdc_python
pip install -e .

Quick Start

from usda_fdc import FdcClient

# Initialize the client with your API key
client = FdcClient("YOUR_API_KEY")

# Search for foods
results = client.search("apple")
for food in results.foods:
    print(f"{food.description} (FDC ID: {food.fdc_id})")

# Get detailed information for a specific food
food = client.get_food(1750340)
print(f"Food: {food.description}")
print(f"Data Type: {food.data_type}")

# Get nutrients for a food
nutrients = client.get_nutrients(1750340)
for nutrient in nutrients:
    print(f"{nutrient.name}: {nutrient.amount} {nutrient.unit_name}")

Command-Line Interface

The library includes two command-line interfaces:

FDC Client CLI

For quick access to FDC data:

# Set your API key (or use --api-key parameter)
export FDC_API_KEY=your_api_key_here

# Search for foods
fdc search "apple"

# Get detailed information for a specific food
fdc food 1750340

# Get nutrients for a food
fdc nutrients 1750340

# List foods with pagination
fdc list --page-size 5 --page-number 1

# Get help
fdc --help

Nutrient Analysis Tool (NAT)

For analyzing nutrient content and recipes:

# Analyze a food
fdc-nat analyze 1750340 --serving-size 100

# Compare multiple foods
fdc-nat compare 1750340 1750341 1750342 --nutrients vitamin_c,potassium,fiber

# Analyze a recipe
fdc-nat recipe --name "Fruit Salad" --ingredients "1 apple" "1 banana" "100g strawberries"

# Generate HTML report
fdc-nat analyze 1750340 --format html --output report.html

# Get help
fdc-nat --help

Nutrient Analysis

The library includes tools for analyzing nutrient content:

from usda_fdc import FdcClient
from usda_fdc.analysis import analyze_food, DriType, Gender

# Initialize the client
client = FdcClient("YOUR_API_KEY")

# Get a food
food = client.get_food(1750340)  # Apple, raw, with skin

# Analyze the food
analysis = analyze_food(
    food,
    dri_type=DriType.RDA,
    gender=Gender.MALE,
    serving_size=100.0
)

# Access the analysis results
print(f"Calories: {analysis.calories_per_serving} kcal")
print(f"Protein: {analysis.get_nutrient('protein').amount} g")
print(f"Vitamin C: {analysis.get_nutrient('vitamin_c').amount} mg")

Recipe Analysis

The library also supports recipe analysis:

from usda_fdc import FdcClient
from usda_fdc.analysis.recipe import create_recipe, analyze_recipe

# Initialize the client
client = FdcClient("YOUR_API_KEY")

# Create a recipe
recipe = create_recipe(
    name="Fruit Salad",
    ingredient_texts=[
        "1 apple",
        "1 banana",
        "100g strawberries"
    ],
    client=client,
    servings=2
)

# Analyze the recipe
analysis = analyze_recipe(recipe)

# Access the analysis results
per_serving = analysis.per_serving_analysis
print(f"Calories per serving: {per_serving.calories_per_serving} kcal")

Visualization

The library includes tools for visualizing nutrient data:

from usda_fdc import FdcClient
from usda_fdc.analysis import analyze_food
from usda_fdc.analysis.visualization import generate_html_report

# Initialize the client
client = FdcClient("YOUR_API_KEY")

# Get and analyze a food
food = client.get_food(1750340)
analysis = analyze_food(food)

# Generate HTML report
html = generate_html_report(analysis)
with open("report.html", "w") as f:
    f.write(html)

Django Integration

The library is designed to work seamlessly with Django applications:

from usda_fdc.django import FdcCache

# Initialize the cache with your Django models
cache = FdcCache()

# Search and cache results
results = cache.search("banana")

# Get food from cache or API
food = cache.get_food(1750340)

# Refresh cache for specific foods
cache.refresh([1750340, 1750341])

Testing

The library includes a comprehensive test suite:

# Install test dependencies
pip install -e ".[dev]"

# Run all unit tests
pytest

# Run integration tests (requires API key)
pytest -m integration

# Run Django tests (requires Django)
pytest -m django

# Run tests with coverage
pytest --cov=usda_fdc

Documentation

For detailed documentation, visit usda-fdc.readthedocs.io.

Configuration

Create a .env file in your project root with the following variables:

FDC_API_KEY=your_api_key_here
FDC_API_URL=https://api.nal.usda.gov/fdc/v1
FDC_CACHE_ENABLED=True
FDC_CACHE_TIMEOUT=86400

Examples

The library includes several example scripts in the examples directory:

• Basic search and retrieval
• Food details and nutrient information
• Nutrient analysis and comparison
• Recipe analysis
• Django integration
• Advanced analysis with meal planning
• Command-line tool usage

Run the examples with:

python examples/01_basic_search.py

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Run the tests to ensure they pass (pytest)
4. Commit your changes (git commit -m 'Add some amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• USDA Food Data Central for providing the API and data
• Inspired by various Python USDA FDC clients