# nutrifyi

[![PyPI version](https://agentgif.com/badge/pypi/nutrifyi/version.svg)](https://pypi.org/project/nutrifyi/)
[![Python](https://img.shields.io/pypi/pyversions/nutrifyi)](https://pypi.org/project/nutrifyi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](https://pypi.org/project/nutrifyi/)

Python API client for nutrition data and food composition analysis. Query macronutrient and micronutrient profiles, look up USDA food composition data, calculate Recommended Dietary Allowances (RDA), and compare nutrient density across foods — all from [NutriFYI](https://nutrifyi.com/), a nutrition reference platform with comprehensive food composition data.

Built on USDA FoodData Central and international food composition databases, NutriFYI provides structured access to calories, protein, fat, carbohydrates, vitamins, minerals, and dietary fiber for thousands of foods — used by nutrition app developers, dietitians, and health-tech platforms.

> **Explore nutrition data at [nutrifyi.com](https://nutrifyi.com/)** — browse [foods](https://nutrifyi.com/foods/), compare [nutrients](https://nutrifyi.com/nutrients/), and calculate dietary intake.

<p align="center">
  <img src="https://raw.githubusercontent.com/fyipedia/nutrifyi/main/demo.gif" alt="nutrifyi demo — food nutrition lookup, macronutrient analysis, and dietary comparison in Python" width="800">
</p>

## Table of Contents

- [Install](#install)
- [Quick Start](#quick-start)
- [What You Can Do](#what-you-can-do)
  - [Macronutrient Profiles](#macronutrient-profiles)
  - [Micronutrients (Vitamins and Minerals)](#micronutrients-vitamins-and-minerals)
  - [Food Comparison](#food-comparison)
  - [Dietary Reference Intakes](#dietary-reference-intakes)
- [Command-Line Interface](#command-line-interface)
- [MCP Server (Claude, Cursor, Windsurf)](#mcp-server-claude-cursor-windsurf)
- [REST API Client](#rest-api-client)
- [API Reference](#api-reference)
- [Learn More About Nutrition](#learn-more-about-nutrition)
- [Also Available](#also-available)
- [Health FYI Family](#health-fyi-family)
- [License](#license)

## Install

```bash
pip install nutrifyi                # Core (zero deps)
pip install "nutrifyi[cli]"         # + Command-line interface
pip install "nutrifyi[mcp]"         # + MCP server for AI assistants
pip install "nutrifyi[api]"         # + HTTP client for nutrifyi.com API
pip install "nutrifyi[all]"         # Everything
```

## Quick Start

```python
from nutrifyi.api import NutriFYI

with NutriFYI() as api:
    # Get full nutrition profile for a food
    food = api.get_food("chicken-breast")
    print(food["calories"])          # 165 kcal per 100g
    print(food["protein"])           # 31.0g
    print(food["fat"])               # 3.6g

    # Search the food database
    results = api.search("quinoa")
    for r in results:
        print(f"{r['name']}: {r['calories']} kcal/100g")

    # List nutrient categories
    nutrients = api.list_nutrients()
```

## What You Can Do

### Macronutrient Profiles

The three macronutrients — protein, carbohydrates, and fat — provide the body's caloric energy. Each macronutrient serves distinct metabolic functions: protein for tissue building (4 kcal/g), carbohydrates for immediate energy (4 kcal/g), and fat for energy storage and hormone synthesis (9 kcal/g).

| Macronutrient | Energy | RDA (Adult) | Primary Function |
|---------------|--------|-------------|-----------------|
| Protein | 4 kcal/g | 0.8 g/kg body weight | Tissue repair, enzymes, immune function |
| Carbohydrates | 4 kcal/g | 130 g/day | Glucose for brain and muscles |
| Fat | 9 kcal/g | 20-35% of calories | Cell membranes, hormones, fat-soluble vitamins |
| Fiber | 0 kcal/g | 25-38 g/day | Gut health, cholesterol reduction |
| Water | 0 kcal | 2.7-3.7 L/day | Every metabolic process |

```python
from nutrifyi.api import NutriFYI

with NutriFYI() as api:
    # Full macronutrient breakdown per 100g
    food = api.get_food("salmon-atlantic")
    print(f"Calories: {food['calories']} kcal")
    print(f"Protein: {food['protein']}g")
    print(f"Fat: {food['fat']}g (Saturated: {food['saturated_fat']}g)")
    print(f"Carbs: {food['carbohydrates']}g")
    print(f"Fiber: {food['fiber']}g")
```

Learn more: [Food Database](https://nutrifyi.com/foods/) · [Glossary](https://nutrifyi.com/glossary/)

### Micronutrients (Vitamins and Minerals)

Micronutrients are required in small amounts but are essential for enzyme function, bone health, immune response, and cellular repair. They divide into fat-soluble vitamins (A, D, E, K — stored in body fat), water-soluble vitamins (B-complex, C — excreted daily), and minerals (macro and trace).

| Category | Nutrients | Key Functions |
|----------|----------|---------------|
| Fat-soluble vitamins | A, D, E, K | Vision, bone health, antioxidant, coagulation |
| Water-soluble vitamins | B1-B12, C, Folate | Energy metabolism, collagen, red blood cells |
| Macro-minerals | Ca, P, Mg, Na, K | Bone structure, nerve function, fluid balance |
| Trace minerals | Fe, Zn, Cu, Se, I | Oxygen transport, immune function, thyroid |

```python
from nutrifyi.api import NutriFYI

with NutriFYI() as api:
    # Get micronutrient data for a food
    food = api.get_food("spinach")
    vitamins = food["vitamins"]
    minerals = food["minerals"]
    print(f"Vitamin A: {vitamins['vitamin_a']} mcg RAE")
    print(f"Iron: {minerals['iron']} mg")
    print(f"Calcium: {minerals['calcium']} mg")
```

Learn more: [Nutrients](https://nutrifyi.com/nutrients/) · [Guides](https://nutrifyi.com/guides/)

### Food Comparison

Comparing foods by nutrient density — nutrients per calorie rather than per weight — reveals which foods deliver the most nutritional value. Leafy greens and organ meats top nutrient density rankings, while refined grains and sugars score lowest.

```python
from nutrifyi.api import NutriFYI

with NutriFYI() as api:
    # Compare two foods side by side
    comparison = api.compare("chicken-breast", "tofu")
    print(f"Protein: {comparison['food1']['protein']}g vs {comparison['food2']['protein']}g")
    print(f"Calories: {comparison['food1']['calories']} vs {comparison['food2']['calories']}")
```

Learn more: [Food Comparison](https://nutrifyi.com/foods/) · [Glossary](https://nutrifyi.com/glossary/)

### Dietary Reference Intakes

Dietary Reference Intakes (DRIs) established by the National Academies provide science-based nutrient intake recommendations. The system includes RDA (Recommended Dietary Allowance), AI (Adequate Intake), UL (Tolerable Upper Intake Level), and EAR (Estimated Average Requirement).

| Term | Definition | Use |
|------|-----------|-----|
| RDA | Meets needs of 97-98% of population | Daily target |
| AI | Used when RDA cannot be determined | Estimated target |
| UL | Maximum safe daily intake | Upper safety limit |
| EAR | Meets needs of 50% of population | Population assessment |

```python
from nutrifyi.api import NutriFYI

with NutriFYI() as api:
    # Look up nutrient RDA values
    nutrients = api.list_nutrients()
    for n in nutrients[:5]:
        print(f"{n['name']}: RDA {n['rda']} {n['unit']}")
```

Learn more: [Dietary Guidelines](https://nutrifyi.com/guides/) · [API Documentation](https://nutrifyi.com/developers/)

## Command-Line Interface

```bash
pip install "nutrifyi[cli]"

nutrifyi food chicken-breast                # Full nutrition profile
nutrifyi search "brown rice"                # Search food database
nutrifyi compare chicken-breast tofu        # Side-by-side comparison
nutrifyi nutrients                          # List all tracked nutrients
```

## MCP Server (Claude, Cursor, Windsurf)

```bash
pip install "nutrifyi[mcp]"
```

```json
{
    "mcpServers": {
        "nutrifyi": {
            "command": "uvx",
            "args": ["--from", "nutrifyi[mcp]", "python", "-m", "nutrifyi.mcp_server"]
        }
    }
}
```

## REST API Client

```python
from nutrifyi.api import NutriFYI

with NutriFYI() as api:
    food = api.get_food("chicken-breast")        # GET /api/v1/foods/chicken-breast/
    nutrients = api.list_nutrients()              # GET /api/v1/nutrients/
    results = api.search("avocado")              # GET /api/v1/search/?q=avocado
```

### Example

```bash
curl -s "https://nutrifyi.com/api/v1/foods/chicken-breast/"
```

```json
{
    "slug": "chicken-breast",
    "name": "Chicken Breast (cooked)",
    "calories": 165,
    "protein": 31.0,
    "fat": 3.6,
    "carbohydrates": 0.0,
    "fiber": 0.0
}
```

Full API documentation at [nutrifyi.com/developers/](https://nutrifyi.com/developers/).

## API Reference

| Function | Description |
|----------|-------------|
| `api.get_food(slug)` | Full nutrition profile (macros + micros) |
| `api.list_foods()` | List all foods in database |
| `api.search(query)` | Search food database |
| `api.compare(food1, food2)` | Side-by-side nutrient comparison |
| `api.list_nutrients()` | All tracked nutrients with RDA values |
| `api.get_nutrient(slug)` | Nutrient details and top food sources |

## Learn More About Nutrition

- **Browse**: [Food Database](https://nutrifyi.com/foods/) · [Nutrients](https://nutrifyi.com/nutrients/)
- **Guides**: [Nutrition Guides](https://nutrifyi.com/guides/) · [Glossary](https://nutrifyi.com/glossary/)
- **API**: [REST API Docs](https://nutrifyi.com/developers/) · [OpenAPI Spec](https://nutrifyi.com/api/openapi.json)

## Also Available

| Platform | Install | Link |
|----------|---------|------|
| **npm** | `npm install nutrifyi` | [npm](https://www.npmjs.com/package/nutrifyi) |
| **MCP** | `uvx --from "nutrifyi[mcp]" python -m nutrifyi.mcp_server` | [Config](#mcp-server-claude-cursor-windsurf) |

## Health FYI Family

Part of the [FYIPedia](https://fyipedia.com) open-source developer tools ecosystem — human body, medicine, and nutrition.

| Package | PyPI | npm | Description |
|---------|------|-----|-------------|
| anatomyfyi | [PyPI](https://pypi.org/project/anatomyfyi/) | [npm](https://www.npmjs.com/package/anatomyfyi) | 14,692 anatomical structures, body systems, organs — [anatomyfyi.com](https://anatomyfyi.com/) |
| pillfyi | [PyPI](https://pypi.org/project/pillfyi/) | [npm](https://www.npmjs.com/package/pillfyi) | Pill identification, FDA drug database — [pillfyi.com](https://pillfyi.com/) |
| drugfyi | [PyPI](https://pypi.org/project/drugfyi/) | [npm](https://www.npmjs.com/package/drugfyi) | Drug interactions, pharmacology, side effects — [drugfyi.com](https://drugfyi.com/) |
| **nutrifyi** | [PyPI](https://pypi.org/project/nutrifyi/) | [npm](https://www.npmjs.com/package/nutrifyi) | **Nutrition data, food composition, dietary analysis — [nutrifyi.com](https://nutrifyi.com/)** |

## License

MIT
