# CompsAPI

Real completed eBay sales as JSON. Up to 1,095 days of history per search, and the
amount a Best Offer sale actually closed at, which eBay's public page never shows.

Base URL: `https://api.compsapi.com`
Auth: `Authorization: Bearer COMPSAPI_KEY`

## Endpoints

| Endpoint | What it returns |
|---|---|
| `GET /v1/sold` | Individual completed sales matching a query |
| `GET /v1/comps` | A cleaned median, spread and the newest matches |
| `GET /v1/usage` | Quota and limits. Free to call, never counts against quota |

## Parameters for /v1/sold

| Name | Notes |
|---|---|
| `q` | The search. Keep it short. Required |
| `days` | 1 to 1095. Free and Starter reach 365, Growth and above reach 1095 |
| `size` | 10 to 240. Values outside that range are rejected |
| `condition` | new, used, open box, refurbished, parts |
| `best_offer` | `1` returns only accepted offer sales, priced at what closed |
| `cards` | `1` populates the card object. Without it grade and grader are empty |
| `grader` `grade` | PSA, BGS, CGC and the numeric grade. Needs `cards=1` |
| `site` | Pins one marketplace. The default merges several |

## Fields on each sale

`item_id`, `title`, `price`, `last_sold` (UTC), `format` (AUCTION or FIXED_PRICE),
`bids`, `shipping_cost`, `units_sold`, `total_sales`, `best_offer`, `url`, `us_sale`.

## Things that will waste your quota if you do not know them

1. **Long queries return nothing.** Pasting a full listing title is the single most
   common cause of zero results. Search `levis 506 jeans`, not
   `Levi's 00506-0391 jeans mens W34 L32 straight leg dark wash`.
2. **A zero result call still costs a request.** There is no free retry.
3. **Queries under three characters are rejected**, not returned empty.
4. **Card numbers are reused across sets.** `4/102` is Base Set Charizard and a
   modern reprint. Add the set name, or filter with `cards=1 graded=true`.
5. **Scarce items read low.** A retired LEGO set returns instructions and single
   minifigures unless you narrow it. Always quote the median AND the spread.
6. **`best_offer=1` only returns offer sales.** Omit it for everything.

## Errors

| Code | Meaning |
|---|---|
| 400 | Bad parameter. The message names it |
| 401 | Key missing, wrong or revoked |
| 429 | Rate limit. Back off, do not hammer |
| 503 | eBay did not answer. Retry once after about a minute |

## Billing

One request is one page of up to 240 sales. Failed requests are not counted.
Free is 100 requests a month. Plans and limits: https://compsapi.com/pricing