# Pokemon Price Tracker API

> Real-time Pokemon card prices, PSA/CGC/BGS grading analytics, and market data for 23,000+ cards.

## Base URL
https://www.pokemonpricetracker.com/api/v2

## Authentication
All requests require Bearer token:
```
Authorization: Bearer YOUR_API_KEY
```
Get your API key at: https://www.pokemonpricetracker.com/api

## OpenAPI Spec
Full machine-readable spec: https://www.pokemonpricetracker.com/api/openapi

## Rate Limits
- Free: 100 credits/day, 60 calls/min
- API ($9.99/mo): 20,000 credits/day, 60 calls/min
- Business ($99/mo): 200,000 credits/day, 200 calls/min

Credit costs: 1 base + 1 if includeHistory + 1 if includeEbay per card

---

## Endpoints

### GET /cards
Search and filter Pokemon cards with pricing data.

**Required:** At least one filter (search, setId, set, tcgPlayerId, rarity, cardType, artist, minPrice, maxPrice)

**Key Parameters:**
- `search` (string): Multi-word search across name, set, number, rarity. Example: "charizard base set holo"
- `tcgPlayerId` (string): Get specific card by ID (returns single object)
- `setId` (string): Filter by set ID or slug
- `includeHistory` (boolean): Include price history (+1 credit per card)
- `includeEbay` (boolean): Include eBay PSA/CGC/BGS graded sales (+1 credit per card)
- `includeBoth` (boolean): Shorthand for includeHistory + includeEbay
- `days` (integer): Days of history (default: 30, max: 365)
- `language` (string): "english" (default) or "japanese"
- `limit` (integer): Max results (default: 50, max: 200, max 50 with eBay data)
- `offset` (integer): Pagination offset

**Response includes:** tcgPlayerId, name, setName, cardNumber, rarity, prices (market, low, listings), image URLs

**Example:**
```
GET /cards?search=charizard%20base%20set&limit=5
GET /cards?tcgPlayerId=233294&includeBoth=true
```

---

### GET /sets
List Pokemon TCG sets.

**Parameters:**
- `search` (string): Search by set name
- `series` (string): Filter by series
- `language` (string): "english" or "japanese"
- `sortBy` (string): name, releaseDate, cardCount
- `limit` (integer): Max 500

**Example:**
```
GET /sets?search=scarlet%20violet
```

---

### GET /sealed-products
Booster boxes, ETBs, and sealed products with pricing.

**Required:** At least one filter

**Parameters:**
- `tcgPlayerId` (string): Specific product ID
- `setId` (string): Filter by set
- `search` (string): Search by product name
- `includeHistory` (boolean): Include price history (+1 credit)

**Example:**
```
GET /sealed-products?search=booster%20box&limit=10
```

---

### GET /population
GemRate grading population data (Business plan only).

**Parameters:**
- `tcgPlayerId` (string): Single card ID
- `tcgPlayerIds` (string): Comma-separated IDs (max 50)
- `grader` (string): Filter by PSA, BGS, CGC, SGC
- `minGemRate` (number): Minimum gem rate percentage

**Credit cost:** 2 per card

**Example:**
```
GET /population?tcgPlayerId=490294
```

---

### POST /parse-title
Parse eBay listing titles to extract card information.

**Request body:**
```json
{
  "title": "Pokemon PSA 10 Charizard VMAX Rainbow 074/073 Champions Path",
  "options": {
    "fuzzyMatching": true,
    "maxSuggestions": 5
  }
}
```

**Credit cost:** 2-5 based on complexity

---

## Common Use Cases

**Get card with full pricing data:**
```
GET /cards?tcgPlayerId=233294&includeBoth=true&days=30
```

**Search for cards:**
```
GET /cards?search=pikachu%20vmax&limit=10
```

**Get all cards in a set:**
```
GET /cards?setId=sv05-temporal-forces&fetchAllInSet=true
```

**Get Japanese cards:**
```
GET /cards?language=japanese&search=Pikachu
```

---

## Response Format
```json
{
  "data": [...],
  "metadata": {
    "total": 100,
    "count": 10,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}
```

## Error Codes
- 400: Missing required filter or invalid parameters
- 401: Invalid or missing API key
- 429: Rate limit exceeded
- 500: Server error