← back to Handbag Auth Nextjs

auction-viewer/API_DOCUMENTATION_V2.md

736 lines

# LUXVAULT Auction Viewer API Documentation v2.0

## Overview

The LUXVAULT Auction Viewer API provides comprehensive access to luxury handbag auction data with advanced filtering, search, and analytics capabilities.

**Base URL:** `http://45.61.58.125:7500`

**API Version:** 2.0.0

**Features:**
- ✅ Pagination (limit/offset and page-based)
- ✅ Advanced filtering (brand, price, date, auction house)
- ✅ Full-text search across multiple fields
- ✅ Multiple sort options
- ✅ Response caching for performance
- ✅ Rate limiting for stability
- ✅ Comprehensive error handling

---

## Authentication

Currently, no authentication is required for read-only endpoints. Rate limiting is applied per IP address.

---

## Rate Limits

- **General API endpoints:** 100 requests per 15 minutes
- **Strict endpoints** (logs, CSV, insights): 20 requests per 5 minutes
- **Download endpoints:** 10 requests per hour

Rate limit headers are included in all responses:
```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699999999
```

---

## Common Response Format

All API responses follow this structure:

```json
{
  "success": true|false,
  "data": [...],
  "count": 50,
  "error": "Error message if success=false"
}
```

---

## Core Endpoints

### 1. Get Auctions (Enhanced)

**Endpoint:** `GET /api/v1/auctions`

**Description:** Retrieve auctions with advanced filtering, sorting, and pagination.

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | 50 | Number of results (1-1000) |
| `offset` | integer | 0 | Pagination offset |
| `page` | integer | 1 | Page number (alternative to offset) |
| `brand` | string | - | Filter by brand/search_term |
| `auction_house` | string | - | Filter by auction house |
| `min_price` | float | - | Minimum current price |
| `max_price` | float | - | Maximum current price |
| `start_date` | ISO8601 | - | Filter by created_at >= date |
| `end_date` | ISO8601 | - | Filter by created_at <= date |
| `search` | string | - | Full-text search query |
| `sort` | string | date | Sort field (price, date, savings, deal_score, relevance) |
| `order` | string | desc | Sort order (asc, desc) |

**Example Requests:**

```bash
# Basic pagination
curl "http://45.61.58.125:7500/api/v1/auctions?limit=20&page=2"

# Filter by brand
curl "http://45.61.58.125:7500/api/v1/auctions?brand=Hermes%20Birkin"

# Price range filter
curl "http://45.61.58.125:7500/api/v1/auctions?min_price=5000&max_price=20000"

# Full-text search
curl "http://45.61.58.125:7500/api/v1/auctions?search=birkin+leather"

# Sort by price
curl "http://45.61.58.125:7500/api/v1/auctions?sort=price&order=asc"

# Combined filters
curl "http://45.61.58.125:7500/api/v1/auctions?brand=Chanel&min_price=1000&max_price=10000&sort=savings&limit=50"
```

**Response:**

```json
{
  "success": true,
  "count": 20,
  "data": [
    {
      "id": 1,
      "auction_id": "LA-12345",
      "title": "Hermes Birkin 30cm Black Togo",
      "auction_house": "Christie's",
      "current_price": 8500.00,
      "estimate_low": 10000.00,
      "estimate_high": 15000.00,
      "end_date": "2025-12-01T18:00:00Z",
      "lot_number": "123",
      "url": "https://example.com/lot/123",
      "search_term": "Hermes Birkin",
      "created_at": "2025-11-17T10:00:00Z",
      "savings_percent": 15.0,
      "savings_amount": 1500.0
    }
  ],
  "total": 2250,
  "limit": 20,
  "offset": 20,
  "page": 2,
  "totalPages": 113,
  "filters": {
    "brand": null,
    "auction_house": null,
    "min_price": null,
    "max_price": null,
    "start_date": null,
    "end_date": null,
    "search": null
  },
  "sort": {
    "field": "date",
    "order": "desc"
  }
}
```

---

### 2. Get Single Auction

**Endpoint:** `GET /api/v1/auctions/:id`

**Description:** Retrieve detailed information about a single auction.

**Example:**

```bash
curl "http://45.61.58.125:7500/api/v1/auctions/123"
```

**Response:**

```json
{
  "success": true,
  "data": {
    "id": 123,
    "auction_id": "LA-12345",
    "title": "Hermes Birkin 30cm Black Togo",
    "auction_house": "Christie's",
    "current_price": 8500.00,
    "estimate_low": 10000.00,
    "estimate_high": 15000.00,
    "end_date": "2025-12-01T18:00:00Z",
    "lot_number": "123",
    "url": "https://example.com/lot/123",
    "search_term": "Hermes Birkin",
    "created_at": "2025-11-17T10:00:00Z",
    "savings_percent": 15.0,
    "savings_amount": 1500.0
  }
}
```

---

### 3. Full-Text Search

**Endpoint:** `GET /api/v1/search`

**Description:** Perform full-text search across auction titles, brands, and auction houses.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Search query |
| `limit` | integer | No | Max results (1-100, default 50) |

**Example:**

```bash
curl "http://45.61.58.125:7500/api/v1/search?q=birkin+leather&limit=20"
```

**Response:**

```json
{
  "success": true,
  "query": "birkin leather",
  "count": 15,
  "data": [...]
}
```

---

### 4. Best Value Auctions

**Endpoint:** `GET /api/best-values`

**Description:** Get auctions with the best value (highest savings).

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `sort` | string | percent | Sort by 'percent' or 'dollar' |
| `limit` | integer | 100 | Max results (1-100) |

**Example:**

```bash
curl "http://45.61.58.125:7500/api/best-values?sort=dollar&limit=50"
```

---

### 5. Statistics

**Endpoint:** `GET /api/stats`

**Description:** Get aggregated statistics about all auctions.

**Example:**

```bash
curl "http://45.61.58.125:7500/api/stats"
```

**Response:**

```json
{
  "success": true,
  "stats": {
    "total": 2250,
    "byBrand": [
      { "search_term": "Hermes Birkin", "count": 324 },
      { "search_term": "Chanel Classic Flap", "count": 287 }
    ],
    "byAuctionHouse": [
      { "auction_house": "Christie's", "count": 523 },
      { "auction_house": "Sotheby's", "count": 412 }
    ],
    "avgPrice": 5471.54,
    "priceRange": {
      "min_price": 327.53,
      "max_price": 93452.0
    }
  }
}
```

---

## Analytics Endpoints

### 6. Deal Scores

**Endpoint:** `GET /api/insights/deal-scores`

**Description:** Get auctions ranked by AI-calculated deal score.

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `limit` | integer | 50 | Max results (1-100) |

**Example:**

```bash
curl "http://45.61.58.125:7500/api/insights/deal-scores?limit=25"
```

---

### 7. Market Trends

**Endpoint:** `GET /api/insights/trends`

**Description:** Get price trends and market analytics by brand.

**Example:**

```bash
curl "http://45.61.58.125:7500/api/insights/trends"
```

---

### 8. Price Anomalies

**Endpoint:** `GET /api/insights/anomalies`

**Description:** Detect price outliers and unusual auction listings.

**Example:**

```bash
curl "http://45.61.58.125:7500/api/insights/anomalies"
```

---

### 9. Brand Analytics

**Endpoint:** `GET /api/insights/brand/:brand`

**Description:** Get detailed analytics for a specific brand.

**Example:**

```bash
curl "http://45.61.58.125:7500/api/insights/brand/Hermes%20Birkin"
```

**Response:**

```json
{
  "success": true,
  "brand": "Hermes Birkin",
  "statistics": {
    "total_auctions": 324,
    "avg_price": 12543.50,
    "min_price": 3500.00,
    "max_price": 95000.00,
    "avg_savings_pct": 18.5
  },
  "recent_auctions": [...],
  "price_history": [
    {
      "month": "2025-11",
      "avg_price": 12800.00,
      "count": 15
    }
  ]
}
```

---

### 10. Time Series Data

**Endpoint:** `GET /api/insights/time-series`

**Description:** Get historical price data for charting.

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `brand` | string | - | Filter by brand |
| `interval` | string | month | Interval (day, week, month) |

**Example:**

```bash
curl "http://45.61.58.125:7500/api/insights/time-series?brand=Hermes%20Birkin&interval=month"
```

---

### 11. Compare Brands

**Endpoint:** `GET /api/insights/compare-brands`

**Description:** Compare statistics across all brands.

**Example:**

```bash
curl "http://45.61.58.125:7500/api/insights/compare-brands"
```

---

### 12. Auction Velocity

**Endpoint:** `GET /api/insights/velocity`

**Description:** Get auction ending frequency by brand.

**Example:**

```bash
curl "http://45.61.58.125:7500/api/insights/velocity"
```

---

### 13. Recommendations

**Endpoint:** `GET /api/insights/recommendations`

**Description:** Get personalized auction recommendations.

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `budget` | float | - | Budget filter |

**Example:**

```bash
curl "http://45.61.58.125:7500/api/insights/recommendations?budget=15000"
```

---

### 14. Market Insights

**Endpoint:** `GET /api/insights/market`

**Description:** Get comprehensive market analysis.

**Example:**

```bash
curl "http://45.61.58.125:7500/api/insights/market"
```

---

## System Endpoints

### 15. Health Check

**Endpoint:** `GET /health`

**Description:** Simple health check for monitoring.

**Example:**

```bash
curl "http://45.61.58.125:7500/health"
```

**Response:**

```json
{
  "status": "healthy",
  "timestamp": "2025-11-17T10:00:00Z"
}
```

---

### 16. System Status

**Endpoint:** `GET /api/status`

**Description:** Detailed system status and metrics.

**Example:**

```bash
curl "http://45.61.58.125:7500/api/status"
```

**Response:**

```json
{
  "success": true,
  "status": {
    "service": "auction-viewer-optimized",
    "version": "2.0.0",
    "environment": "production",
    "uptime": 3600.5,
    "memory": {
      "rss": 123456789,
      "heapTotal": 98765432,
      "heapUsed": 65432109
    },
    "database": true,
    "csv": true,
    "logs": true,
    "dbSize": 1234567,
    "csvSize": 234567,
    "logSize": 34567,
    "cache": {
      "size": 45,
      "maxSize": 100,
      "totalHits": 1234,
      "hitRate": 27.42
    },
    "timestamp": "2025-11-17T10:00:00Z"
  }
}
```

---

### 17. Cache Management

**Endpoint:** `POST /api/cache/invalidate`

**Description:** Invalidate cache entries (admin use).

**Request Body:**

```json
{
  "pattern": "auctions:*"  // Optional regex pattern
}
```

**Example:**

```bash
curl -X POST "http://45.61.58.125:7500/api/cache/invalidate" \
  -H "Content-Type: application/json" \
  -d '{"pattern": "auctions:*"}'
```

---

## Data Export Endpoints

### 18. Get CSV Data

**Endpoint:** `GET /api/csv`

**Description:** Get CSV data as JSON string.

---

### 19. Download CSV

**Endpoint:** `GET /api/download-csv`

**Description:** Download CSV file directly.

**Example:**

```bash
curl -O "http://45.61.58.125:7500/api/download-csv"
```

---

### 20. Get Logs

**Endpoint:** `GET /api/logs`

**Description:** Get recent scraper log entries.

**Query Parameters:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `lines` | integer | 100 | Number of lines (1-500) |

**Example:**

```bash
curl "http://45.61.58.125:7500/api/logs?lines=50"
```

---

## Error Codes

| Code | Description |
|------|-------------|
| 200 | Success |
| 400 | Bad Request (validation failed) |
| 404 | Not Found |
| 413 | Payload Too Large |
| 429 | Too Many Requests (rate limited) |
| 500 | Internal Server Error |

**Error Response Format:**

```json
{
  "success": false,
  "error": "Error message",
  "details": [...]  // Only in development mode
}
```

---

## Caching

The API implements intelligent caching:

- **Auction lists:** 1 minute cache
- **Statistics:** 5 minutes cache
- **Analytics:** 10 minutes cache
- **Individual auctions:** 1 hour cache

Cache headers are included in responses:
```
Cache-Control: public, max-age=300
```

---

## Performance Tips

1. **Use pagination:** Always use `limit` and `offset` for large datasets
2. **Filter early:** Apply filters to reduce result size
3. **Use caching:** Repeated queries benefit from caching
4. **Specific queries:** More specific queries = faster responses
5. **Avoid wildcards:** Full-text search is fast but specific terms are better

---

## Code Examples

### JavaScript (Fetch)

```javascript
async function getAuctions(filters = {}) {
  const params = new URLSearchParams(filters);
  const response = await fetch(
    `http://45.61.58.125:7500/api/v1/auctions?${params}`
  );
  return await response.json();
}

// Usage
const auctions = await getAuctions({
  brand: 'Hermes Birkin',
  min_price: 5000,
  max_price: 20000,
  sort: 'savings',
  limit: 50
});
```

### Python (Requests)

```python
import requests

def get_auctions(filters=None):
    url = "http://45.61.58.125:7500/api/v1/auctions"
    response = requests.get(url, params=filters)
    return response.json()

# Usage
auctions = get_auctions({
    'brand': 'Hermes Birkin',
    'min_price': 5000,
    'max_price': 20000,
    'sort': 'savings',
    'limit': 50
})
```

### cURL

```bash
# Get filtered auctions
curl -G "http://45.61.58.125:7500/api/v1/auctions" \
  --data-urlencode "brand=Hermes Birkin" \
  --data-urlencode "min_price=5000" \
  --data-urlencode "max_price=20000" \
  --data-urlencode "sort=savings" \
  --data-urlencode "limit=50"

# Search auctions
curl -G "http://45.61.58.125:7500/api/v1/search" \
  --data-urlencode "q=birkin leather togo"

# Get brand analytics
curl "http://45.61.58.125:7500/api/insights/brand/Hermes%20Birkin"
```

---

## Migration from v1

The new v2 API maintains backward compatibility with existing endpoints:

| Old Endpoint | New Endpoint | Notes |
|--------------|--------------|-------|
| `/api/auctions` | `/api/v1/auctions` | Old endpoint redirects to new |
| `/api/best-values` | `/api/best-values` | Unchanged |
| `/api/stats` | `/api/stats` | Unchanged |

New features in v2:
- Full-text search
- Advanced filtering
- Multiple sort options
- Page-based pagination
- Query caching
- Enhanced analytics

---

## Support

For issues or questions:
- Check server logs: `GET /api/logs`
- Check system status: `GET /api/status`
- Monitor health: `GET /health`

---

**Last Updated:** 2025-11-17
**API Version:** 2.0.0
**Server:** LUXVAULT Auction Viewer Optimized