Analytics API

Endpoints for collection statistics, consumption analytics, valuation, and event tracking.

Overview

The Analytics API provides insights into your beer collection — consumption trends, valuation, top styles, and activity events.

All endpoints require authentication via session cookie or API key.

Consumption Analytics

GET /api/v1/analytics/consumption

Get consumption trends over time.

Query Parameters:

Parameter	Type	Default	Description
`period`	string	`month`	`week`, `month`, `year`, `all`
`groupBy`	string	`date`	`date`, `style`, `brewery`

Response:

JSON

{
  "success": true,
  "data": {
    "period": "month",
    "totalConsumed": 15,
    "averageRating": 3.8,
    "topStyles": [
      { "style": "IPA", "count": 5, "avgRating": 4.1 },
      { "style": "Stout", "count": 4, "avgRating": 4.3 }
    ],
    "topBreweries": [
      { "brewery": "Sierra Nevada", "count": 3 },
      { "brewery": "Founders", "count": 2 }
    ],
    "timeline": [
      { "date": "2024-01-15", "count": 2, "avgRating": 4.0 },
      { "date": "2024-01-22", "count": 1, "avgRating": 3.5 }
    ]
  }
}

Valuation Analytics

GET /api/v1/analytics/valuation

Get collection value estimates.

Response:

JSON

{
  "success": true,
  "data": {
    "totalValue": 2450.00,
    "currency": "USD",
    "averageItemValue": 35.50,
    "topValueItems": [
      {
        "beerName": "Rare Barrel-Aged Stout",
        "estimatedValue": 150.00,
        "originalPrice": 45.00
      }
    ],
    "valueByStyle": [
      { "style": "Barrel-Aged Stout", "totalValue": 800.00 },
      { "style": "Sour", "totalValue": 450.00 }
    ]
  }
}

Activity Events

GET /api/v1/analytics/events

Track collection activity over time.

Query Parameters:

Parameter	Type	Default	Description
`type`	string	—	Filter by event type
`from`	string	—	Start date (ISO 8601)
`to`	string	—	End date (ISO 8601)
`limit`	number	50	Max results
`offset`	number	0	Pagination offset

Event Types:

collection_add — Beer added to collection
collection_consume — Beer consumed
rating_create — New rating created
listing_create — Marketplace listing created
transaction_complete — Sale/purchase completed

Response:

JSON

{
  "success": true,
  "data": {
    "events": [
      {
        "id": "uuid",
        "eventType": "collection_add",
        "targetType": "beer",
        "targetId": "uuid",
        "metadata": { "beerName": "Pliny the Elder", "quantity": 2 },
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 142,
    "limit": 50,
    "offset": 0
  }
}

Collection Statistics (via MCP)

The get_collection_stats MCP tool provides a quick summary:

JSON

{
  "totalBeers": 85,
  "totalBottles": 142,
  "consumedCount": 57,
  "availableCount": 85,
  "uniqueStyles": 18,
  "uniqueBreweries": 34,
  "estimatedValue": 2450.00,
  "averageRating": 3.9
}

Alerts

GET /api/v1/alerts

Get active alerts for your collection.

Response:

JSON

{
  "success": true,
  "data": {
    "alerts": [
      {
        "id": "uuid",
        "type": "best_before",
        "message": "3 beers approaching best-before date",
        "severity": "warning",
        "items": [
          { "beerName": "Fresh Hop IPA", "bestBefore": "2024-02-15" }
        ]
      }
    ]
  }
}

Recommendations

GET /api/v1/recommendations

Get personalized beer recommendations.

Query Parameters:

Parameter	Type	Default	Description
`limit`	number	10	Max recommendations
`style`	string	—	Filter by style

Response:

JSON

{
  "success": true,
  "data": {
    "recommendations": [
      {
        "beer": { "id": "uuid", "name": "Heady Topper", "style": "DIPA", "brewery": "The Alchemist" },
        "score": 0.95,
        "reason": "Based on your high ratings of double IPAs"
      }
    ]
  }
}

Reminders

GET /api/v1/reminders

Get collection reminders.

Response:

JSON

{
  "success": true,
  "data": {
    "reminders": [
      {
        "id": "uuid",
        "type": "drink_window",
        "message": "Optimal drinking window for Barrel-Aged Stout",
        "dueDate": "2024-06-01",
        "collectionItem": { "id": "uuid", "beerName": "Bourbon County Stout" }
      }
    ]
  }
}

Error Codes

Code	HTTP Status	Description
`INVALID_PERIOD`	400	Invalid analytics period
`INVALID_DATE_RANGE`	400	Date range is invalid
`INTERNAL_ERROR`	500	Server error

Next Steps

Collection API — Manage your collection
Ratings API — Rate beers
MCP Server — Access analytics via AI