# WatchPatrol - Full Documentation for AI Agents

> Community-powered watch search engine aggregating listings from watch enthusiast forums worldwide.

## Overview

WatchPatrol is a search engine that aggregates watch listings from popular enthusiast forums and communities. We help users discover pre-owned, vintage, and new watches for sale, compare prices, and research seller reputation.

## Site Structure

### Main Sections

1. **Search/Browse** (`/`)
   - Default view shows latest listings
   - Supports filtering by query, brand, seller, source, date range, price
   - Grid and masonry view options

2. **Discover** (`/discover/`)
   - Top brands and popular watches
   - Price tier categories (under $500, $1000, $2500, $5000, over $5000)
   - Regional categories (Swiss, German, Japanese, American watches)
   - Type categories (dive watches, dress watches, chronographs)

3. **Brand Pages** (`/discover/brands/{slug}/`)
   - Brand information (established date, origin country, description)
   - Most popular models for the brand
   - Top sellers for the brand
   - Price statistics

4. **Listing Details** (`/listing/{id}/`)
   - Full listing description and images
   - Price analysis vs market median
   - Seller feedback and reputation
   - Related watches

## REST API

### Authentication

All API endpoints require authentication:
- Header: `Authorization: Token {your_token}`
- Or: `X-API-Key: {your_api_key}`

### Endpoints

#### Search Listings
```
GET /api/listings/
```
Parameters:
- `query` (string): Search term
- `brand` (string): Filter by brand name
- `username` (string): Filter by seller
- `source` (string): Filter by forum domain
- `price_min` (integer): Minimum price
- `price_max` (integer): Maximum price
- `currency` (string): USD, EUR, GBP, CHF, JPY
- `date_range` (integer): Days (7, 14, 30, 90)
- `page` (integer): Page number

Response:
```json
{
  "count": 1234,
  "next": "/api/listings/?page=2",
  "results": [
    {
      "id": 12345,
      "post_title": "Rolex Submariner 116610LN",
      "price": 11500,
      "currency": "USD",
      "username": "seller123",
      "source": "reddit.com",
      "post_date": "2024-01-15T10:30:00Z",
      "url": "https://reddit.com/r/watchexchange/...",
      "brand": "Rolex",
      "model": "Submariner",
      "has_images": true
    }
  ]
}
```

#### Get Brands
```
GET /api/discover/brands/
```
Returns list of all brands with listing counts.

#### Top Watches
```
GET /api/discover/top-watches/
GET /api/discover/top-watches/price/{price}/
GET /api/discover/top-watches/region/{region}/
GET /api/discover/top-watches/type/{type}/
```
Price tiers: 500, 1000, 2500, 5000, 5001 (over 5000)
Regions: swiss, german, japanese, american
Types: dive, dress, chronograph, quartz

#### Price Analysis
```
GET /api/pricing/{watch_id}/
```
Returns price statistics for similar watches:
- Median, Q1, Q3 prices
- Price distribution
- Historical price trend

#### Seller Feedback
```
GET /api/seller/{username}/
```
Returns:
- Total feedback count
- Positive feedback percentage
- Recent transactions
- Feedback comments

## Data Model

### Watch Listing
- `id`: Unique identifier
- `post_title`: Listing title
- `post_body`: Full description (HTML)
- `post_body_text`: Plain text description
- `price`: Listed price (may be null)
- `currency`: Currency code
- `username`: Seller username
- `source`: Forum/community source
- `post_date`: When listing was posted
- `url`: Original listing URL
- `brand`: Brand object (may be null)
- `model`: Model object (may be null)
- `has_images`: Boolean
- `images`: Array of image URLs
- `tags`: Array of detected tags (vintage, quartz, etc.)

### Brand
- `brandname`: Display name
- `slug`: URL-friendly identifier
- `description`: Brand description
- `established`: Year founded
- `origin`: Country of origin
- `url`: Official website
- `q1_price`, `median_price`, `q3_price`: Price statistics

### Source (Forum)
- `name`: Display name
- `domain`: Website domain
- `lang`: Language code (en, fr, de, es, it)

## Common Use Cases

### Finding Watches
1. Search by model: `GET /api/listings/?query=speedmaster`
2. Filter by brand and price: `GET /api/listings/?brand=Omega&price_max=5000`
3. Find deals: Compare listing price to `GET /api/pricing/{id}/` median

### Researching Sellers
1. Get seller history: `GET /api/seller/{username}/`
2. Check positive feedback percentage
3. Review recent transaction comments

### Price Research
1. Get price stats: `GET /api/pricing/{watch_id}/`
2. Compare to Q1 (25th percentile) for deals
3. Compare to Q3 (75th percentile) for premium pricing

## Rate Limits

- 100 requests per minute for authenticated users
- Respect `Retry-After` header on 429 responses

## Terms of Use

- Data is for personal/research use
- Do not scrape or bulk download
- Attribution required for public use
- Commercial use requires partnership agreement

## Contact

- Website: https://www.watchpatrol.net
- Contact form: /contact/
- API support: api@watchpatrol.net