🥑 Avocavo Python SDK

⚠️ This service is shutting down

The Avocavo Nutrition API stops accepting requests on November 1, 2026. This package will stop working on that date. New signups and purchases are already closed.

The underlying data is USDA FoodData Central, which offers a free public API at https://fdc.nal.usda.gov/api-guide.html. Nutritionix, Edamam and Spoonacular are commercial alternatives.

Structured nutrition data API with USDA-based calculations where applicable. Consistent nutrition estimates for apps and workflows.

🚀 Quick Start

import avocavo

# Login to your account (OAuth flow)
avocavo.login()

# Analyze a single ingredient
result = avocavo.analyze("1 cup brown rice")
print(f"Calories: {result.nutrition.calories}")

# Analyze a recipe
recipe = avocavo.analyze_recipe([
    "2 large eggs",
    "1 cup all-purpose flour", 
    "1/2 cup milk"
])
print(f"Total calories: {recipe.total_nutrition.calories}")

📦 Installation

pip install avocavo

Requirements:

• Python >= 3.8
• Internet connection for API access

🔐 Authentication

1. Sign up at nutrition.avocavo.app
2. Login via Python:

   import avocavo
   avocavo.login()  # Opens browser for secure OAuth
   

3. Your credentials are stored securely in your system keyring

📖 Basic Usage

Single Ingredient Analysis

import avocavo

# Simple ingredient analysis
result = avocavo.analyze("1 cup quinoa, cooked")

print(f"Calories: {result.nutrition.calories}")
print(f"Protein: {result.nutrition.protein}g")
print(f"Fiber: {result.nutrition.fiber}g")

# Access USDA match information
print(f"USDA Food: {result.usda_match.description}")
print(f"Confidence: {result.usda_match.confidence_score}")

Recipe Analysis

# Analyze a complete recipe
ingredients = [
    "2 cups rolled oats",
    "1 banana, mashed", 
    "1/2 cup blueberries",
    "1 cup almond milk"
]

recipe = avocavo.analyze_recipe(ingredients)

# Get totals
print(f"Total Calories: {recipe.total_nutrition.calories}")
print(f"Total Protein: {recipe.total_nutrition.protein}g")

# Get per-serving (if servings specified)
print(f"Per Serving: {recipe.per_serving_nutrition.calories} calories")

# Individual ingredient breakdown
for ingredient in recipe.ingredients:
    print(f"{ingredient.original_input}: {ingredient.nutrition.calories} cal")

Batch Analysis

# Analyze multiple ingredients efficiently
ingredients = [
    "1 cup rice",
    "100g chicken breast",
    "1 medium apple",
    "2 tbsp olive oil"
]

results = avocavo.analyze_batch(ingredients)

for result in results:
    print(f"{result.original_input}: {result.nutrition.calories} calories")

🔧 Advanced Usage

Using the Client Class

from avocavo import NutritionAPI

# Initialize client (uses stored credentials)
client = NutritionAPI()

# Analyze with additional options
result = client.analyze_ingredient(
    "1 cup rice", 
    include_sub_nutrients=True,
    portion_precision="high"
)

# Get detailed nutrition breakdown
nutrients = result.nutrition.detailed_nutrients
for nutrient in nutrients:
    print(f"{nutrient.name}: {nutrient.amount}{nutrient.unit}")

Account Management

import avocavo

# Check your usage
usage = avocavo.get_account_usage()
print(f"Requests used: {usage.requests_used}/{usage.requests_limit}")

# Get current user info
user = avocavo.get_current_user()
print(f"Logged in as: {user.email}")

# Manage API keys
api_keys = avocavo.list_api_keys()
for key in api_keys:
    print(f"Key: {key.name} (Created: {key.created_at})")

🔒 Security Features

• 🔐 Secure Authentication: OAuth flow with system keyring storage
• 🛡️ SSL Verification: All API calls use secured HTTPS connections
• 🔑 No Hardcoded Secrets: Credentials stored securely, never in code
• 🚫 Input Sanitization: All inputs properly validated and sanitized

📊 Data Models

Nutrition Object

nutrition = result.nutrition

# Macronutrients
print(nutrition.calories)      # kcal
print(nutrition.protein)       # grams
print(nutrition.carbs)         # grams  
print(nutrition.fat)           # grams
print(nutrition.fiber)         # grams

# Micronutrients
print(nutrition.sodium)        # mg
print(nutrition.calcium)       # mg
print(nutrition.iron)          # mg
print(nutrition.vitamin_c)     # mg

USDA Match Information

match = result.usda_match

print(match.fdc_id)           # USDA FDC ID
print(match.description)      # Food description
print(match.confidence_score) # Match confidence (0-1)
print(match.data_type)        # SR Legacy, Foundation, etc.

🚨 Error Handling

from avocavo import ApiError

try:
    result = avocavo.analyze("invalid ingredient")
except ApiError as e:
    print(f"API Error: {e.message}")
    print(f"Status Code: {e.status_code}")
    
    if e.status_code == 401:
        print("Authentication required - run avocavo.login()")
    elif e.status_code == 429:
        print("Rate limit exceeded - upgrade your plan")

📚 Examples

Meal Planning

import avocavo

# Plan a day of meals
breakfast = avocavo.analyze_recipe([
    "2 eggs, scrambled",
    "1 slice whole wheat toast",
    "1/2 avocado"
])

lunch = avocavo.analyze_recipe([
    "4 oz grilled chicken",
    "1 cup quinoa",
    "1 cup steamed broccoli"
])

dinner = avocavo.analyze_recipe([
    "6 oz salmon fillet",
    "1 cup brown rice", 
    "1 cup roasted vegetables"
])

# Calculate daily totals
daily_calories = (breakfast.total_nutrition.calories + 
                 lunch.total_nutrition.calories + 
                 dinner.total_nutrition.calories)

print(f"Daily Total: {daily_calories} calories")

Recipe Scaling

# Original recipe for 4 servings
original = avocavo.analyze_recipe([
    "2 cups flour",
    "4 eggs",
    "1 cup milk"
], servings=4)

# Scale to 8 servings (double)
scale_factor = 8 / 4

scaled_ingredients = []
for ingredient in original.ingredients:
    # Extract amount and scale (simplified example)
    scaled_amount = ingredient.parsed_amount * scale_factor
    scaled_ingredients.append(f"{scaled_amount} {ingredient.parsed_unit} {ingredient.parsed_food}")

scaled_recipe = avocavo.analyze_recipe(scaled_ingredients, servings=8)

🆘 Support

• Documentation: nutrition.avocavo.app/docs/python
• API Dashboard: nutrition.avocavo.app
• Issues: GitHub Issues
• Email: api-support@avocavo.com

📄 License

MIT License - see LICENSE file for details.

🔄 Migrating from avocavo-nutrition?

The old package has been deprecated due to security vulnerabilities. Migration is straightforward:

# Remove old package
pip uninstall avocavo-nutrition

# Install new secure package
pip install avocavo

Code changes:

# OLD (deprecated)
import avocavo_nutrition as av
av.login()

# NEW (secure)
import avocavo
avocavo.login()

All functionality remains the same - only the import and security have been improved!