API Documentation

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

Quick Navigation

Important — Intended Use

Avocavo is a structured nutrition data API intended for informational use in apps, workflows, logging, search, and estimation. Results are derived from USDA FoodData Central and third-party product databases and may vary based on preparation, brand, or portion size. This API is not suitable for official food labeling, allergen safety determinations, clinical nutrition decisions, or any use requiring regulatory compliance. Developers are responsible for verifying data accuracy before production use. Not affiliated with or endorsed by USDA.

1️⃣ Overview / Quick Start

📌 What is Avocavo Nutrition API?

Avocavo Nutrition API gives you USDA-linked 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

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 "Content-Type: application/json" \
  -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 "Content-Type: application/json" \
  -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 "Content-Type: application/json" \
  -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 "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"upc": "041196912395"}'

Response:

{
  "success": true,
  "ingredient": "1 cup rice",
  "nutrition": {
    "calories": 205.0,
    "protein": 4.3,
    "carbohydrates": 44.5,
    "fiber": 0.6
  },
  "metadata": {
    "usda_match": {
      "fdc_id": 169756,
      "description": "Rice, white, medium-grain, enriched, cooked"
    },
    "usda_link": "https://fdc.nal.usda.gov/fdc-app.html#/food-details/169756",
    "processing_time_ms": 1.2
  }
}

✅ /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,
  "batch_size": 2,
  "results": [
    {
      "success": true,
      "id": "rice1",
      "ingredient": "1 cup rice",
      "nutrition": { "calories": 205.0, "protein": 4.3 },
      "metadata": { "usda_match": { "fdc_id": 169756 } }
    },
    {
      "success": true,
      "id": "chicken1", 
      "ingredient": "100g chicken breast",
      "nutrition": { "calories": 165.0, "protein": 31.0 },
      "metadata": { "usda_match": { "fdc_id": 171477 } }
    }
  ],
  "summary": {
    "successful": 2,
    "failed": 0,
    "success_rate": 100.0,
    "total_processing_time_ms": 42.1
  }
}

✅ /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": {
    "servings": 4.0,
    "total_ingredients": 3
  },
  "metadata": {
    "fallback_strategy": "normal_processing",
    "processing_time_ms": 3140.45
  },
  "nutrition": {
    "per_serving": {
      "calories": 162.3,
      "protein": 6.8,
      "carbohydrates": 26.5,
      "total_fat": 3.7
    },
    "ingredients": [
      {
        "ingredient": "1 cup flour",
        "nutrition": { "calories": 455.0, "protein": 12.9 },
        "metadata": { "usda_match": { "fdc_id": 169761 } }
      }
      // ... milk and egg
    ]
  }
}

✨ /analyze (NEW)

Extract and analyze multiple ingredients from conversational, free-form text up to 2000 characters.

Request Body:

{
  "text": "1 piece of toast with butter 1 cup of coffee"
}

Response:

{
  "success": true,
  "source_text": "1 piece of toast with butter 1 cup of coffee",
  "extracted_ingredients": [
    "1 piece toast",
    "1 pat butter",
    "1 cup coffee"
  ],
  "results": [
    // ... complete ingredient nutrition data ...
  ],
  "summary": { "successful": 3, "failed": 0, "success_rate": 100.0 },
  "metadata": { "extraction_method": "gpt", "tokens_used": 142 }
}

✨ /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 "Content-Type: application/json" \
  -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",
  "nutrition": { "calories": 205.0, "protein": 4.3 },
  "metadata": {
    "usda_match": { "fdc_id": 169756 },
    "usda_link": "https://fdc.nal.usda.gov/fdc-app.html#/food-details/169756"
  }
}

✅ Batch:

[
  { "id": "rice1", "ingredient": "1 cup rice", "nutrition": { "calories": 205.0 }, "metadata": { "usda_match": { "fdc_id": 169756 } } },
  { "id": "chicken1", "ingredient": "100g chicken breast", "nutrition": { "calories": 165.0 }, "metadata": { "usda_match": { "fdc_id": 171477 } } }
]

✅ Recipe:

{
  "recipe": { "servings": 4.0, "total_ingredients": 3 },
  "metadata": { "processing_time_ms": 3140.45 },
  "nutrition": {
    "per_serving": {
      "calories": 162.3,
      "protein": 6.8,
      "carbohydrates": 26.5,
      "total_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
    }
  }
}

Note on ingredient and allergen data: Ingredient lists and allergen information returned by UPC/barcode endpoints are sourced from third-party databases (USDA Branded Foods, Open Food Facts) and may be incomplete, outdated, or absent. This data is provided as-is for informational purposes. It is not a substitute for official product label information and must not be used as the sole basis for allergen safety decisions. Always verify against the physical product label.

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

Plan	Monthly Requests	Burst Rate
Free Trial	500	50 requests / 10 seconds
Starter	5,000	100 requests / 10 seconds
Pro	25,000	200 requests / 10 seconds
Enterprise	150,000	500 requests / 10 seconds

Batch Processing Limits

Plan	Max Ingredients per Batch	Notes
Free	3 ingredients	Single ingredients recommended
Starter	8 ingredients	Small batch processing
Professional	25 ingredients	Production batch processing
Enterprise	50+ ingredients	Custom 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