`EBAY_INTEGRATION.md`

226 lines
# eBay Sold Listings Integration

Display real sales history for handbag valuation and auction pricing.

## Features

✅ **Real Sales Data** - Actual sold prices from eBay (not asking prices)
✅ **90-Day History** - Track sales over customizable time periods
✅ **Sales Statistics** - Count, Average, Median, Min, Max prices
✅ **Visual Charts** - Beautiful area charts showing price trends
✅ **Recent Sales List** - Clickable links to actual sold listings
✅ **Condition Filtering** - See prices by condition (New, Excellent, Good, etc.)

## Setup

### 1. Get eBay API Key (Free)

1. Go to https://developer.ebay.com/
2. Sign up for a developer account
3. Create an application
4. Get your App ID (Client ID)

### 2. Configure Environment Variable

```bash
# Add to .env.local
EBAY_APP_ID=YourAppIdHere
```

### 3. API Endpoint

**Endpoint:** `GET /api/ebay-sold`

**Parameters:**
- `query` - Search keywords (e.g., "Hermes Birkin 35")
- `brand` - Brand name (alternative to query)
- `model` - Model name (used with brand)
- `daysBack` - Days to search back (default: 90, max: 90)
- `maxResults` - Max results to return (default: 50, max: 100)

**Example Request:**
```bash
GET /api/ebay-sold?brand=Hermes&model=Birkin 35&daysBack=90
```

**Response:**
```json
{
  "success": true,
  "query": "Hermes Birkin 35",
  "count": 42,
  "sold_listings": [
    {
      "item_id": "123456789",
      "title": "Authentic Hermes Birkin 35 Togo Black Gold Hardware",
      "price_usd": 14500.00,
      "currency": "USD",
      "condition": "Pre-owned",
      "end_time": "2025-11-10T15:30:00.000Z",
      "location": "Beverly Hills, CA",
      "url": "https://www.ebay.com/itm/123456789",
      "image_url": "https://..."
    }
  ],
  "statistics": {
    "count": 42,
    "avg_price": 13250.50,
    "median_price": 12900.00,
    "min_price": 9500.00,
    "max_price": 18000.00
  },
  "date_range": {
    "from": "2025-08-16T00:00:00.000Z",
    "to": "2025-11-14T23:59:59.000Z",
    "days": 90
  }
}
```

## React Component Usage

```tsx
import { EbaySalesChart } from '@/components/EbaySalesChart'

export default function ProductPage() {
  return (
    <div>
      <h1>Hermès Birkin 35</h1>

      {/* Show eBay sales history */}
      <EbaySalesChart
        brand="Hermes"
        model="Birkin 35"
        daysBack={90}
      />
    </div>
  )
}
```

## Integration Examples

### 1. Price Tracker Page

Add eBay sales data alongside internal price history:

```tsx
// src/app/price-tracker/page.tsx
import { PriceHistoryChart } from '@/components/PriceHistoryChart'
import { EbaySalesChart } from '@/components/EbaySalesChart'

{selectedItem && (
  <>
    {/* Internal price history */}
    <PriceHistoryChart
      externalId={selectedItem.externalId}
      listingId={selectedItem.id}
      brand={selectedItem.brand}
      model={selectedItem.model}
    />

    {/* eBay sold listings */}
    <EbaySalesChart
      brand={selectedItem.brand}
      model={selectedItem.model}
      daysBack={90}
    />
  </>
)}
```

### 2. Auction Valuation

Show comparable sales for items up for auction:

```tsx
// Show current auction item with sales comps
<div>
  <h2>Current Auction</h2>
  <p>Starting bid: $8,000</p>
  <p>Auction ends: Nov 20, 2025</p>

  <h3>Comparable Sales (eBay)</h3>
  <EbaySalesChart
    brand={auctionItem.brand}
    model={auctionItem.model}
    daysBack={60}
  />
</div>
```

### 3. Deal Verification

Use eBay data to verify if Japanese marketplace prices are truly deals:

```tsx
const listing = { /* Japanese marketplace item */ }
const ebaySales = await fetch(`/api/ebay-sold?brand=${listing.brand}&model=${listing.model}`)
const data = await ebaySales.json()

const isDeal = listing.priceUsd < data.statistics.avg_price * 0.8
```

## Benefits

### For Buyers
- **Informed Bidding** - Know fair market value before bidding
- **Deal Verification** - Confirm Japanese prices are actually cheaper
- **Price Trends** - See if prices are rising or falling
- **Condition Comparison** - Compare prices by condition

### For Sellers
- **Pricing Guidance** - Set competitive starting bids
- **Market Analysis** - Understand demand and pricing trends
- **Authenticity Validation** - Cross-reference with authenticated sales

## Technical Details

### eBay Finding API

Uses the free eBay Finding API (no authentication required):
- Endpoint: `https://svcs.ebay.com/services/search/FindingService/v1`
- Operation: `findCompletedItems`
- Filter: `SoldItemsOnly = true`
- Rate Limit: 5,000 calls/day (free tier)

### Data Accuracy

✅ **Real Sales** - Only includes "EndedWithSales" listings (actual sales, not just ended)
❌ **Not Asking Prices** - Excludes listings that ended without sale
✅ **Currency Conversion** - All prices converted to USD
✅ **Condition Noted** - Includes item condition for comparison

### Performance

- **Response Time**: ~500ms - 1.5s (eBay API)
- **Cache Strategy**: Consider caching for 6-24 hours
- **Fallback**: Graceful degradation if eBay is unavailable

## Python Alternative

For batch analysis or data collection:

```bash
cd python-matcher/scripts
export EBAY_APP_ID="your_app_id"
python3 ebay_sold_scraper.py
```

## Notes

- eBay data is US-centric (prices in USD)
- 90-day limit on historical data (eBay API restriction)
- Free tier: 5,000 calls/day
- Consider implementing caching for frequently searched items
- Combine with internal price history for complete picture

## Future Enhancements

- [ ] Save eBay sales data to database
- [ ] Historical tracking (>90 days by storing data)
- [ ] Price prediction using sales trends
- [ ] Alert when current price < 80% of eBay average
- [ ] Condition-specific comparisons
- [ ] Geographic price variations