# AutoTrader UK API — search used and new car listings on autotrader.co.uk with full advert detail: price, price indicator, mileage, spec, images and dealer reviews (US market: use the cars-com engine)

> UK car listings (make/model + filters, paginated); postcode defaults to a UK centroid if omitted
> ReefAPI engine `autotrader` · 2 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/autotrader/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /autotrader/v1/search — 1 credit
UK car listings (make/model + filters, paginated); postcode defaults to a UK centroid if omitted

**Parameters:**
- `make` (string, optional) — Vehicle make / manufacturer (e.g. 'BMW', 'Ford').
- `model` (string, optional) — Vehicle model (e.g. '3 Series'). Use together with make.
- `postcode` (string, optional) — UK postcode to anchor the location-based search (defaults to a central England postcode if omitted).
- `min_price` (integer, optional) — Minimum price in GBP.
- `max_price` (integer, optional) — Maximum price in GBP.
- `min_year` (integer, optional) — Earliest year of manufacture.
- `max_year` (integer, optional) — Latest year of manufacture.
- `min_mileage` (integer, optional) — Minimum mileage (miles).
- `max_mileage` (integer, optional) — Maximum mileage (miles).
- `fuel` (enum, optional) — Fuel type. Common values shown; other AutoTrader fuel labels are also accepted (forwarded to the FilterName enum). [one of: Petrol, Diesel, Electric, Hybrid, Plug-in Hybrid]
- `body_type` (enum, optional) — Body style. Common values shown; other AutoTrader body labels are also accepted. [one of: Hatchback, Saloon, Estate, SUV, Coupe, Convertible, MPV]
- `transmission` (enum, optional) — Gearbox type. [one of: Manual, Automatic]
- `radius` (integer, optional) — Search radius in miles around the postcode.
- `page` (integer, optional, default 1) — Results page (paginated). Default 1.
- `market` (enum, optional, default "uk") — Marketplace region. Only 'uk' returns listings; 'us' is currently unavailable (use the cars-com engine for US). [one of: uk, us]

**Returns:** listings[]{advertId, title, price, rrp, make, model, year, mileage, vehicleLocation, sellerType, images, fpaLink, ...}, page_info{page, page_count, total_results}, market

**Example request body:**
```json
{
  "make": "BMW",
  "model": "3 Series",
  "postcode": "SW1A 1AA",
  "market": "uk"
}
```

### POST /autotrader/v1/listing_detail — 1 credit
Full advert (price+priceIndicator+deviation, mileage, full spec [fuel/trans/body/doors/seats/engine], description, images[], dealer+reviews+address)

**Parameters:**
- `id` (integer, required) — AutoTrader advert id (the digits in a /car-details/<id> URL or a search listing's advertId). Provide id OR url.
- `url` (string, optional) — Full advert URL (alternative to id; the id is parsed from /car-details/<id>).
- `postcode` (string, optional) — UK postcode to anchor the location-based search (defaults to a central England postcode if omitted).
- `market` (enum, optional, default "uk") — Marketplace region. Only 'uk' returns listings; 'us' is currently unavailable (use the cars-com engine for US). [one of: uk, us]

**Returns:** listing{price, priceIndicatorRating, priceDeviation, mileage, registration, year, specification{make,model,fuel,transmission,bodyType,doors,seats,engine}, description, images[], dealer{name,reviews,location}}, market

## More
- Try it live, no code: https://reefapi.com/playground?engine=autotrader
- Human docs page: https://reefapi.com/docs/autotrader
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt