Avocavo LogoAvocavo Nutrition

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 typically 300-400ms responses.

🚀 Get Started with SDKs

Py

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://app.avocavo.app/api/v2/nutrition/ingredient \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"ingredient": "1 cup rice"}'

# Or search UPC/barcode
curl -X POST https://app.avocavo.app/api/v2/upc/ingredient \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"upc": "041196912395"}'

✅ See Authentication to get your token.

2️⃣ Authentication

📌 How to Authenticate

All API calls require an API key via X-API-Key header or OAuth login through our SDKs.

✅ CLI Login (recommended)

avocavo login

✅ cURL Header

-H "X-API-Key: YOUR_API_KEY"

✅ Security

•API key authentication for direct REST API access
•OAuth2.0 flows for SDK login (secure)
•HTTPS only
•Rate limiting and tier-based access control

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://app.avocavo.app/api/v2/nutrition/ingredient \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"ingredient": "1 cup rice"}'

# Or search UPC/barcode
curl -X POST https://app.avocavo.app/api/v2/upc/ingredient \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"upc": "041196912395"}'

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 (3), Starter (8), Professional (25), 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
  }
}

✨ /upc/ingredient (NEW)

Search for product information by UPC/barcode. Access 4.4M+ products from USDA Branded Foods and Open Food Facts databases.

Request Body:

{
  "upc": "041196912395"
}

Example cURL:

curl -X POST https://app.avocavo.app/api/v2/upc/ingredient \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"upc": "041196912395"}'

Response:

{
  "success": true,
  "upc": "041196912395",
  "product": {
    "product_name": "Peanut Butter Crunch",
    "brand": "LEWIS BAKE SHOP",
    "sources": ["usda_branded", "open_food_facts"],
    "categories": ["en:breads", "en:sausages"],
    "serving_size": "66g",
    "nutrition": {
      "energy_kcal": 52.9,
      "proteins": 10.6,
      "carbohydrates": 2.9,
      "fat": 0
    },
    "ingredients_text": "Unbleached enriched wheat flour..."
  },
  "response_time_ms": 184
}

✨ /upc/batch (NEW)

Search multiple UPCs/barcodes in a single request for efficient batch processing.

Request Body:

{
  "upcs": ["041196912395", "123456789012", "012000161155"]
}

Response:

{
  "success": true,
  "summary": {
    "total": 3,
    "found": 2,
    "errors": 0
  },
  "results": [
    {
      "upc": "041196912395",
      "success": true,
      "product": {
        "product_name": "Peanut Butter Crunch",
        "brand": "LEWIS BAKE SHOP"
      }
    },
    {
      "upc": "123456789012",
      "success": false,
      "error": "Product not found"
    }
  ],
  "processing_time_ms": 1146
}

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
  }
}

✨ UPC/Barcode (NEW):

{
  "success": true,
  "upc": "041196912395",
  "product": {
    "product_name": "Peanut Butter Crunch",
    "brand": "LEWIS BAKE SHOP",
    "sources": ["usda_branded", "open_food_facts"],
    "nutrition": {
      "energy_kcal": 52.9,
      "proteins": 10.6
    }
  }
}

5️⃣ CLI and SDK Usage

✅ CLI

# Install
npm install -g avocavo

# Login with OAuth
avocavo login

# Analyze ingredient
avocavo ingredient "1 cup rice"

# Search UPC/barcode
avocavo upc "041196912395"

# Batch UPC search
avocavo upc-batch -u "041196912395" "123456789012"

✅ Python SDK

pip install avocavo

import avocavo as av
av.login()

# Analyze ingredient
result = av.analyze_ingredient("2 tbsp olive oil")

# Search UPC/barcode
upc_result = av.search_upc("041196912395")
if upc_result.found:
    print(f"Product: {upc_result.product.product_name}")

✅ NPM CLI

avocavo login
avocavo ingredient "100g chicken breast"
avocavo upc "041196912395"

✅ 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: 'computer'"
}

✅ Common Errors:

•400: Bad Input
•401: Unauthorized
•429: Rate Limit Exceeded
•500: Server Error

7️⃣ Rate Limits

PlanHourly LimitPer-Minute LimitBurst Rate
Free1,000 / hour100 / minuteUp to 50 requests / 10 seconds
Starter2,500 / hour500 / minuteUp to 100 requests / 10 seconds
Professional10,000 / hour1,000 / minuteUp to 200 requests / 10 seconds
Business50,000 / hour5,000 / minuteCustom limits with SLAs

Batch Processing Limits

PlanMax Ingredients per BatchNotes
Free3 ingredientsSingle ingredients recommended
Starter8 ingredientsSmall batch processing
Professional25 ingredientsProduction batch processing
Enterprise50+ ingredientsCustom limits available on request

✅ Enterprise solutions with custom limits are available for high-volume usage.

8️⃣ Pricing

✅Multiple pricing tiers available for different usage needs
✅Flexible pricing with pay-as-you-go options
✅Various subscription plans available

Multiple pricing tiers are available to support different usage patterns and requirements. Each plan includes various API call limits and features to accommodate different use cases.

✅ For detailed pricing information, refer to the pricing documentation

9️⃣ FAQs

✅ What is this API for?

For developers who need USDA-verifiable nutrition data in clean JSON for meal planning, recipes, diet apps, and more.

✅ What data source do you use?

USDA FoodData Central with real FDC IDs and verification URLs.

✅ Do you support recipes and batches?

Yes! Analyze single ingredients, batch lists, or full recipes with serving calculations.

✅ How do I authenticate?

Secure OAuth 2.0 login. No API keys to manage.

✅ How fast is it?

Typically 300-400ms per request with intelligent caching.

✅ What pricing plans are available?

Multiple pricing tiers are available to accommodate different usage levels and requirements.

✅ Can I store the nutrition results in my database?

Yes! Once you request nutrition data, it's yours to use, store, cache, and serve in your app however you want. No usage restrictions.

✅ What are the limits for batch requests?

Batch limits vary by plan:

  • • Free: 3 ingredients per batch
  • • Starter: 8 ingredients per batch
  • • Professional: 25 ingredients per batch
  • • Enterprise: 50 ingredients per batch

For larger batches, split them into multiple requests.

10️⃣ Links & Resources

✅NPM Package
✅Python Package
✅NPM Package
✅Python Package

Need Help?

We're here to help you integrate our API successfully into your application.

Contact SupportSystem Status