`auction-viewer/ANALYTICS_QUICKREF.md`

347 lines
# LUXVAULT Analytics - Quick Reference

## 10 Analytics Endpoints

### 1. Deal Scores - Top Opportunities
```bash
GET /api/insights/deal-scores?limit=20
```
**Returns:** Auctions ranked by Deal Score (0-100) algorithm
**Use:** Find best deals based on savings, price, urgency, and historical performance

---

### 2. Price Trends - Market Direction
```bash
GET /api/insights/trends
```
**Returns:** Price trends by brand with direction (increasing/decreasing)
**Use:** Understand market movements and timing

---

### 3. Anomalies - Outliers & Rare Finds
```bash
GET /api/insights/anomalies
```
**Returns:** Statistical outliers (z-score > 2)
**Use:** Find exceptionally priced items or rare pieces

---

### 4. Price Prediction - Forecast
```bash
GET /api/insights/predict/:auction_id
```
**Returns:** Predicted final price with confidence interval
**Use:** Estimate where auction will close

---

### 5. Recommendations - Personalized Deals
```bash
GET /api/insights/recommendations?budget=5000
```
**Returns:** Top 20 recommendations filtered by budget
**Use:** Get personalized auction suggestions

---

### 6. Market Insights - Overview
```bash
GET /api/insights/market
```
**Returns:** Market summary, price distribution, top value brands
**Use:** Understand overall market health

---

### 7. Brand Analytics - Deep Dive
```bash
GET /api/insights/brand/Hermes%20Birkin
```
**Returns:** Brand statistics, recent auctions, price history
**Use:** Research specific brands

---

### 8. Time-Series - Chart Data
```bash
GET /api/insights/time-series?brand=Chanel%20Boy&interval=month
```
**Returns:** Historical data for charts (Chart.js ready)
**Use:** Visualize price trends over time

---

### 9. Brand Comparison - Market Position
```bash
GET /api/insights/compare-brands
```
**Returns:** Comparative metrics across all brands
**Use:** Compare value propositions

---

### 10. Velocity - Urgency Tracker
```bash
GET /api/insights/velocity
```
**Returns:** Auctions ending soon by brand
**Use:** Track time-sensitive opportunities

---

## Deal Score Formula

**Total: 100 points**

1. **Savings Percentage** (40 pts): How far below estimate
2. **Price vs Brand Average** (25 pts): Relative value
3. **Time Urgency** (20 pts): Days until auction ends
4. **Price Percentile** (15 pts): Position within brand pricing

**Interpretation:**
- 80-100: Exceptional deal
- 60-79: Great value
- 40-59: Good opportunity
- 20-39: Fair deal
- 0-19: Premium price

---

## Example Use Cases

### Find Best Deals Under $3000
```bash
curl "http://45.61.58.125:7500/api/insights/recommendations?budget=3000"
```

### Check if Current Price is Good
```bash
curl "http://45.61.58.125:7500/api/insights/predict/LA-104A9D16A3F1"
# Compare predicted vs current price
```

### Monitor Market Trends
```bash
curl "http://45.61.58.125:7500/api/insights/trends" | jq '.data."Hermes Birkin"'
```

### Find Rare/Special Items
```bash
curl "http://45.61.58.125:7500/api/insights/anomalies" | jq '.data[] | select(.anomaly_type == "unusually_high")'
```

### Get Brand Comparison
```bash
curl "http://45.61.58.125:7500/api/insights/compare-brands" | jq '.data | sort_by(.avg_savings_pct) | reverse | .[0:5]'
```

---

## Cache Times

| Endpoint | Cache | Refresh Rate |
|----------|-------|--------------|
| deal-scores | 5 min | Frequent updates |
| trends | 10 min | Stable data |
| anomalies | 10 min | Infrequent changes |
| market | 10 min | Aggregate stats |
| predict | None | Real-time |
| recommendations | 5 min | Dynamic filtering |
| brand | 5 min | Active data |
| time-series | 10 min | Historical |
| compare-brands | 10 min | Market-wide |
| velocity | 5 min | Time-sensitive |

---

## Response Format

All endpoints return:
```json
{
  "success": true/false,
  "data": {...} or [...],
  "count": number (for arrays),
  "generated_at": "ISO timestamp",
  "error": "message" (if failed)
}
```

---

## Integration Examples

### Chart.js - Price Trend Chart
```javascript
const response = await fetch('/api/insights/time-series?brand=Chanel Boy&interval=month');
const { data } = await response.json();

new Chart(ctx, {
  type: 'line',
  data: {
    labels: data.map(d => d.period),
    datasets: [{
      label: 'Average Price',
      data: data.map(d => d.avg_price)
    }]
  }
});
```

### Deal Alert System
```javascript
async function checkDeals() {
  const response = await fetch('/api/insights/deal-scores?limit=10');
  const { data } = await response.json();

  const exceptional = data.filter(d => d.deal_score >= 80);
  if (exceptional.length > 0) {
    sendAlert(`${exceptional.length} exceptional deals found!`);
  }
}
```

### Price Watch
```javascript
async function watchAuction(auctionId) {
  const prediction = await fetch(`/api/insights/predict/${auctionId}`).then(r => r.json());
  const auction = await fetch(`/api/auctions`).then(r => r.json());

  const current = auction.data.find(a => a.auction_id === auctionId);

  if (current.current_price < prediction.data.predicted_final_price * 0.8) {
    return "Strong Buy - 20% below predicted";
  } else if (current.current_price > prediction.data.predicted_final_price * 1.2) {
    return "Overpriced - 20% above predicted";
  }
  return "Fair Price";
}
```

---

## Testing

```bash
# Test all endpoints
for endpoint in deal-scores trends anomalies market recommendations compare-brands velocity; do
  echo "Testing $endpoint..."
  curl -s "http://45.61.58.125:7500/api/insights/$endpoint" | jq '.success'
done

# Test parameterized endpoints
curl -s "http://45.61.58.125:7500/api/insights/brand/Hermes%20Birkin" | jq '.success'
curl -s "http://45.61.58.125:7500/api/insights/predict/LA-104A9D16A3F1" | jq '.success'
curl -s "http://45.61.58.125:7500/api/insights/time-series?brand=Chanel%20Boy" | jq '.success'
```

---

## Server Status

```bash
# Check server health
pm2 status auction-viewer

# View logs
pm2 logs auction-viewer --lines 50

# Restart if needed
pm2 restart auction-viewer
```

---

## Direct Python Access

```bash
cd /root/Projects/handbag-auth-nextjs/auction-viewer

# Get deal scores
python3 analytics-engine.py ../data/auction-history/auctions.db deal-scores 10

# Get market insights
python3 analytics-engine.py ../data/auction-history/auctions.db market-insights

# Get trends
python3 analytics-engine.py ../data/auction-history/auctions.db trends

# Get anomalies
python3 analytics-engine.py ../data/auction-history/auctions.db anomalies

# Get recommendations
python3 analytics-engine.py ../data/auction-history/auctions.db recommendations 5000

# Predict price
python3 analytics-engine.py ../data/auction-history/auctions.db predict LA-104A9D16A3F1
```

---

## Common Queries

### Top 5 Brands by Value
```bash
curl -s "http://45.61.58.125:7500/api/insights/compare-brands" | \
  jq '.data | sort_by(.avg_savings_pct) | reverse | .[0:5] | .[] | {brand, avg_savings_pct, avg_price}'
```

### Deals Ending Today
```bash
curl -s "http://45.61.58.125:7500/api/insights/velocity" | \
  jq '.data | sort_by(.ending_today) | reverse | .[0:5]'
```

### Price Distribution
```bash
curl -s "http://45.61.58.125:7500/api/insights/market" | \
  jq '.data.price_distribution'
```

### Brand Price History
```bash
curl -s "http://45.61.58.125:7500/api/insights/brand/Louis%20Vuitton%20Neverfull" | \
  jq '.price_history'
```

---

## Performance Tips

1. **Use caching**: Respect cache-control headers
2. **Limit requests**: Use appropriate limits for your needs
3. **Batch queries**: Combine data from fewer endpoints
4. **Filter early**: Use budget/brand filters to reduce data transfer
5. **Monitor rate limits**: Stay within 100 req/15min

---

## Troubleshooting

### No data returned
- Check if database has data: `sqlite3 auctions.db "SELECT COUNT(*) FROM auctions;"`
- Verify filters aren't too restrictive

### Slow responses
- Check if cache is working (response headers)
- Monitor Python script execution time
- Review database query performance

### Errors
- Check logs: `/root/Projects/handbag-auth-nextjs/auction-viewer/logs/error.log`
- Verify Python dependencies installed
- Test analytics script directly

---

## Quick Links

- **Server**: http://45.61.58.125:7500
- **API Base**: http://45.61.58.125:7500/api/insights
- **Dashboard**: http://45.61.58.125:7500
- **Health Check**: http://45.61.58.125:7500/health
- **Documentation**: ANALYTICS_DOCUMENTATION.md