API Documentation

USDA-verifiable nutrition data in clean, structured JSON. Designed for developers.

Quick Navigation

1️⃣ Overview / Quick Start

📌 What is Avocavo Nutrition API?

Avocavo Nutrition API gives you USDA-verifiable nutrition data in clean, structured JSON.

✅Handles single ingredients, batch lists, and full recipes with serving-based nutrition.

✅Official FoodData Central IDs and verification URLs.

✅Designed for developers with CLI, NPM, and Python SDKs.

✅OAuth-secured authentication with fast (~200ms typical) responses.

🚀 Get Started with SDKs

Python SDK

Complete Python package with OAuth, API key management, and nutrition analysis

View Python Documentation →

CLI

Command Line Tool

Cross-platform CLI with secure credential storage and batch processing

View CLI Documentation →

📌 Quick Start Example

# Authenticate with OAuth
avocavo login

# Analyze single ingredient
avocavo ingredient "1 cup brown rice"

✅ Or use our REST API with cURL:

curl -X POST https://nutrition.avocavo.app/api/v1/nutrition/ingredient \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"ingredient": "1 cup rice"}'

✅ See Authentication to get your token.

2️⃣ Authentication

📌 How to Authenticate

All API calls require an OAuth Bearer token.

✅ CLI Login (recommended)

avocavo login

✅ cURL Header

-H "Authorization: Bearer YOUR_TOKEN"

✅ Security

•OAuth2.0 flows (secure login)

•HTTPS only

•No API keys to lose or leak

3️⃣ Endpoints

✅ /ingredient

Analyze a single ingredient with portion-aware parsing.

Request Body:

{
  "ingredient": "1 cup brown rice, cooked"
}

Example cURL:

curl -X POST https://nutrition.avocavo.app/api/v1/nutrition/ingredient \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"ingredient": "1 cup rice"}'

Response:

{
  "success": true,
  "ingredient": "1 cup rice",
  "nutrition": {
    "calories_total": 205,
    "protein_total": 4.3,
    "total_fat_total": 0.4,
    "carbohydrates_total": 44.5,
    "fiber_total": 0.6,
    "sodium_total": 1.6
  },
  "usda_match": {
    "fdc_id": 169756,
    "description": "Rice, white, medium-grain, enriched, cooked",
    "data_type": "sr_legacy_food"
  },
  "verification_url": "https://fdc.nal.usda.gov/fdc-app.html#/food-details/169756"
}

✅ /batch

Analyze multiple ingredients in a single request. Batch limits vary by plan: Free (5), Starter (10), Professional (20), Enterprise (50+).

Request Body:

{
  "ingredients": [
    {"ingredient": "1 cup rice", "id": "rice1"},
    {"ingredient": "100g chicken breast", "id": "chicken1"}
  ]
}

Response:

{
  "success": true,
  "results": [
    {
      "id": "rice1",
      "ingredient": "1 cup rice",
      "nutrition": {
        "calories_total": 205,
        "protein_total": 4.3,
        "fdc_id": 169756
      }
    },
    {
      "id": "chicken1", 
      "ingredient": "100g chicken breast",
      "nutrition": {
        "calories_total": 165,
        "protein_total": 31.0,
        "fdc_id": 171477
      }
    }
  ]
}

✅ /recipe

Analyze a complete recipe with serving-based nutrition.

Request Body:

{
  "recipe_name": "Classic Pancakes",
  "servings": 4,
  "ingredients": [
    "1 cup flour",
    "1 cup milk", 
    "1 egg"
  ]
}

Response:

{
  "success": true,
  "recipe_name": "Classic Pancakes",
  "servings": 4,
  "ingredients": [
    {
      "ingredient": "1 cup flour",
      "nutrition": {
        "calories": 455,
        "protein": 12.9,
        "fdc_id": 169761
      }
    },
    {
      "ingredient": "1 cup milk",
      "nutrition": {
        "calories": 122,
        "protein": 8.1,
        "fdc_id": 173441
      }
    },
    {
      "ingredient": "1 egg",
      "nutrition": {
        "calories": 72,
        "protein": 6.3,
        "fdc_id": 171287
      }
    }
  ],
  "totals_per_serving": {
    "calories": 162.3,
    "protein": 6.8,
    "carbs": 26.5,
    "fat": 3.7
  }
}

4️⃣ Example Responses

✅ Single Ingredient:

{
  "ingredient": "1 cup rice",
  "calories_total": 205,
  "protein_total": 4.3,
  "fdc_id": 169756,
  "verification_url": "https://fdc.nal.usda.gov/fdc-app.html#/food-details/169756"
}

✅ Batch:

[
  { "ingredient": "1 cup rice", "calories_total": 205, "fdc_id": 169756 },
  { "ingredient": "100g chicken breast", "calories_total": 165, "fdc_id": 171477 }
]

✅ Recipe:

{
  "recipe_name": "Classic Pancakes",
  "servings": 4,
  "totals_per_serving": {
    "calories": 162.3,
    "protein": 6.8,
    "carbs": 26.5,
    "fat": 3.7
  }
}

5️⃣ CLI and SDK Usage

✅ CLI

# Install
npm install -g avocavo-nutrition-cli

# Login with OAuth
avocavo login

# Analyze
avocavo ingredient "1 cup rice"

✅ Python SDK

pip install avocavo-nutrition

import avocavo_nutrition as av
av.login()
result = av.analyze_ingredient("2 tbsp olive oil")

✅ NPM CLI

avocavo login
avocavo ingredient "100g chicken breast"

✅ See full SDK docs on PyPI and NPM.

6️⃣ Error Handling

✅ Example Error Response:

{
  "success": false,
  "error": "ingredient_not_usda_verified",
  "message": "Could not find USDA match for: &apos;computer&apos;"
}

✅ Common Errors:

•400: Bad Input

•401: Unauthorized

•429: Rate Limit Exceeded

•500: Server Error

7️⃣ Rate Limits

Plan	Hourly Limit	Per-Minute Limit	Burst Rate
Free	1,000 / hour	100 / minute	Up to 50 requests / 10 seconds
Starter	2,500 / hour	500 / minute	Up to 100 requests / 10 seconds
Professional	10,000 / hour	1,000 / minute	Up to 200 requests / 10 seconds
Business	50,000 / hour	5,000 / minute	Custom limits with SLAs

Batch Processing Limits

Plan	Max Ingredients per Batch	Notes
Free	5 ingredients	Single ingredients recommended
Starter	10 ingredients	Small batch processing
Professional	20 ingredients	Production batch processing
Enterprise	50+ ingredients	Custom limits available on request