AutoTrader API & Scraper
The AutoTrader UK API returns used- and new-car listings from one of the UK's largest car marketplaces as clean JSON.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
The primary search endpoint returns listings with advert id, title, price, RRP, make, model, year, mileage, location, seller type and images, and you can pull a listing_detail. It is built for automotive pricing, dealer tools and UK car-market analytics that need AutoTrader data without a scraper. One ReefAPI key, one shared credit pool, the standard envelope.
What an AutoTrader UK search row actually contains
The search action returns 20 listings per page, and several values people expect as their own fields are not fields at all. Mileage, the price-indicator rating and the registration plate identifier all live inside the badges array. These values were read off live BMW 3 Series and Ford Fiesta searches on 2026-08-27.
| Field | Measured value | What it means |
|---|---|---|
| advert_id | "202608135062814" | 15-digit string; the first 8 digits are a YYYYMMDD stamp (2026-08-13). This is the number in a /car-details/<id> URL. |
| price / price_formatted | 7795 / "£7,795" | price is a plain integer in GBP, price_formatted is display text. currency is always "GBP". |
| badges[0] | "Great price", "Good price", "Lower price" | AutoTrader's price indicator for the advert. There is no separate price-indicator field on a search row. |
| badges (mileage) | "63,000 miles", "183,000 miles" | Mileage is a formatted string inside badges. Search returns no numeric mileage field. |
| badges (plate) | "2017 (66 reg)", "2019 (19 reg)" | Year plus the UK registration plate identifier. The numeric year is also on the row as year. |
| seller_type | "TRADE" or "PRIVATE" | Uppercase. TRADE rows also carry dealer_link; private rows return dealer_link null. |
| location / distance | "Altrincham (8 miles)" / {value: 8, unit: null} | Distance from the postcode you passed, in miles. unit comes back null, and the radius parameter is miles too. |
| rrp, discount, monthly_finance, dealer_rating | null | All four were null on every used-car row sampled. rrp is a new-car field. |
| condition / vehicle_category | "used" / "car" | Lowercase values on every row sampled. |
| market | "uk" | market="us" returns the error code MARKET_UNAVAILABLE, not an empty list — this engine covers the UK. |
Pagination is 20 listings per page. A BMW 3 Series search anchored on SW1A 1AA returned total_results 6884 across page_count 345; a filtered Ford Fiesta search near M1 1AE returned 1157 across 58 pages. total_results is the market-wide count for your filters, not the number of rows in the response.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/autotrader/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"make": "BMW",
"model": "3 Series",
"postcode": "SW1A 1AA",
"market": "uk"
}
}{
"ok": true,
"meta": {
"api": "autotrader",
"endpoint": "search",
"mode": "live",
"latency_ms": 1804.7,
"record_count": 20,
"bytes": 22640,
"cache_hit": false,
"market": "uk",
"page": 1,
"page_count": 351,
"total_results": 7005,
"postcode": "SW1A 1AA",
"postcode_defaulted": false
},
"data": {
"market": "uk",
"listings": [
{
"advert_id": "[redacted-phone]",
"title": "BMW 3 Series",
"subtitle": "2.0 320i M Sport Business Edition Euro 5 4dr",
"attention_grabber": "Part X to clear-runs and drive",
"price": 2495,
"price_formatted": "£2,495",
"currency": "GBP",
"rrp": null,
"discount": null,
"monthly_finance": null,
"make": "BMW",
"model": "3 Series",
"year": 2010,
"condition": "used",
"vehicle_category": "car",
"location": "Sandy (45 miles)",
"location_type": "STANDARD",
"distance": {
"value": 45,
"unit": null
},
"seller_type": "TRADE",
"dealer_rating": 4.7,
"dealer_link": "https://www.autotrader.co.uk/dealers/bedfordshire/sandy/one-class-auto-limited-10037829?channel=cars",
"image_count": 20,
"images": [
"https://m.atcdn.co.uk/a/media/w800h600/191c5e89c9f44ea5bc9b312f14cb5b2b.jpg",
"https://m.atcdn.co.uk/a/media/w800h600/8e8b9b3e9bc54b3bae380cda40f9f031.jpg",
"https://m.atcdn.co.uk/a/media/w800h600/7e8520e3cdb94d99855a27dfcb0f03d9.jpg"
],
"badges": [
"95,000 miles",
"2010 (10 reg)"
],
"url": "https://www.autotrader.co.uk/car-details/[redacted-phone]?sort=relevance&twcs=true&searchId="
},
{
"advert_id": "[redacted-phone]",
"title": "BMW 3 Series",
"subtitle": "2.0 318i ES Auto Euro 4 4dr",
"attention_grabber": "BARGAIN | READ DESCRIPTION",
"price": 500,
"price_formatted": "£500",
"currency": "GBP",
"rrp": null,
"discount": null,
"monthly_finance": null,
"make": "BMW",
"model": "3 Series",
"year": 2007,
"condition": "used",
"vehicle_category": "car",
"location": "Kingston Upon Thames (10 miles)",
"location_type": "STANDARD",
"distance": {
"value": 10,
"unit": null
},
"seller_type": "TRADE",
"dealer_rating": null,
"dealer_link": null,
"image_count": 9,
"images": [
"https://m.atcdn.co.uk/a/media/w800h600/23d912ff41e74a25a[redacted-phone]a3d2d6.jpg",
"https://m.atcdn.co.uk/a/media/w800h600/819900dee1474f919d96c6959d63dfd3.jpg",
"https://m.atcdn.co.uk/a/media/w800h600/f1782f57453343ba95a3f3821ac04381.jpg"
],
"badges": [
"105,000 miles",
"2007 (57 reg)"
],
"url": "https://www.autotrader.co.uk/car-details/[redacted-phone]?sort=relevance&searchId="
},
{
"advert_id": "[redacted-phone]",
"title": "BMW 3 Series",
"subtitle": "2.2 320i SE 4dr",
"attention_grabber": null,
"price": 990,
"price_formatted": "£990",
"currency": "GBP",
"rrp": null,
"discount": null,
"monthly_finance": null,
"make": "BMW",
"model": "3 Series",
"year": 2002,
"condition": "used",
"vehicle_category": "car",
"location": "Croydon (8 miles)",
"location_type": "STANDARD",
"distance": {
"value": 8,
"unit": null
},
"seller_type": "TRADE",
"dealer_rating": 3.7,
"dealer_link": "https://www.autotrader.co.uk/dealers/surrey/croydon/dvp-car-sales-ltd-10008582?channel=cars",
"image_count": 25,
"images": [
"https://m.atcdn.co.uk/a/media/w800h600/47cc0f92063e445795e2abc861e69b18.jpg",
"https://m.atcdn.co.uk/a/media/w800h600/84f8bd1584d44c29a0732b07286571c6.jpg",
"https://m.atcdn.co.uk/a/media/w800h600/d1c6568f45cd4460acb50ed42f26aa87.jpg"
],
"badges": [
"157,000 miles",
"2002 (02 reg)"
],
"url": "https://www.autotrader.co.uk/car-details/[redacted-phone]?sort=relevance&twcs=true&searchId="
}
],
"page_info": {
"page": 1,
"page_count": 351,
"total_results": 7005,
"search_id": ""
}
}
}What the AutoTrader API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | UK car listings (make/model + filters, paginated); postcode defaults to a UK centroid if omitted | Pricing teams call search to get uK car listings (make/model + filters, paginated); postcode defaults to a UK centroid if omitted. | make, model, postcode, min_price, max_price, ... |
| listing_detail | Full advert (price+priceIndicator+deviation, mileage, full spec [fuel/trans/body/doors/seats/engine], description, images[], dealer+reviews+address) | Marketplace operators call listing_detail to get full advert (price+priceIndicator+deviation, mileage, full spec [fuel/trans/body/doors/seats/…. | id, postcode, market |
Call search from your stack
curl -X POST https://api.reefapi.com/autotrader/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"make":"BMW","model":"3 Series","postcode":"SW1A 1AA","market":"uk"}'import requests
r = requests.post(
"https://api.reefapi.com/autotrader/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"make": "BMW",
"model": "3 Series",
"postcode": "SW1A 1AA",
"market": "uk"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/autotrader/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"make": "BMW",
"model": "3 Series",
"postcode": "SW1A 1AA",
"market": "uk"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.autotrader.search with {"make":"BMW","model":"3 Series","postcode":"SW1A 1AA","market":"uk"}.Who uses this API and why
- Automotive pricing tools call search to track used-car prices by make, model and mileage.
- Dealer-intelligence products filter search by seller type to monitor trade vs private listings.
- Market analysts use listing_detail to study price-vs-RRP and depreciation across the UK market.
Questions developers ask before integrating
Is this AutoTrader UK or AutoTrader US?
AutoTrader UK, autotrader.co.uk. The market parameter accepts "us", but a US search returns the error code MARKET_UNAVAILABLE rather than listings, measured on 2026-08-27. For US car listings use the cars-com engine instead. Everything else follows from that: prices are GBP, mileage is miles, and locations are anchored on a UK postcode.
What is the format of an AutoTrader advert_id?
A 15-digit string whose first eight digits are a date in YYYYMMDD form. Six ids sampled on 2026-08-27 decoded to 2026-08-25, 2026-08-13, 2026-07-30, 2026-07-24, 2026-06-18 and 2026-05-22, so the leading block tells you roughly how long an advert has been up. It is the same number that appears in the advert URL as /car-details/<id>, and it is what listing_detail takes as id.
Where is the mileage? There is no mileage field on a search result.
Mileage is a formatted string inside badges, for example "63,000 miles". Search rows carry price, year, make, model and condition as typed fields, but mileage, the price-indicator rating and the plate identifier are all badge entries. If you need a number, strip the commas and the word yourself, or use min_mileage and max_mileage to filter server-side, since those parameters do take integers.
What does the "Great price" or "Lower price" badge mean?
It is AutoTrader's own price indicator for the advert, comparing the asking price against what the site thinks the car is worth. Values seen on live results include "Great price", "Good price" and "Lower price", and they always sit first in the badges array when present. Not every advert has one, and those rows open straight onto the mileage badge instead.
Why does listing_detail reject a request that only has url?
Despite the parameter description reading "Provide id OR url", sending only url returns MISSING_PARAM with the message "missing: id", measured 2026-08-27. Parse the digits out of the /car-details/<id> path yourself and send them as id. url is best treated as an extra hint alongside id rather than a substitute for it.
What does a TARGET_BLOCKED response from listing_detail mean?
It means the advert page did not come back on that attempt, and it is flagged retryable: true, so a repeat is the right response rather than a code change. In a 2026-08-27 check listing_detail returned TARGET_BLOCKED on four consecutive advert ids while search kept working normally. Search rows already carry price, year, make, model, images, seller_type and the mileage badge, so most pipelines can fall back to search while retrying detail.
How many results per page, and how deep can I page?
20 listings per page. The response repeats page, page_count and total_results in meta and again in data.page_info, plus a search_id that ties the pages of one query together. total_results is the number of adverts matching your filters market-wide, 6884 for BMW 3 Series near SW1A 1AA on 2026-08-27, so divide by 20 to see how deep page_count goes before you start looping.
Which fuel, body_type and transmission values does search accept?
transmission is a strict pair, Manual or Automatic. fuel is documented as Petrol, Diesel, Electric, Hybrid and Plug-in Hybrid, and body_type as Hatchback, Saloon, Estate, SUV, Coupe, Convertible and MPV, but both are pass-through: other AutoTrader labels are forwarded rather than rejected. All three ignore an invalid value, so a label the site does not recognize silently drops the filter instead of erroring. Compare total_results with and without it if you need to be sure a filter took.
What is the AutoTrader API?
AutoTrader API is a ReefAPI endpoint group for new and used car listings with prices and specs. It returns live JSON through POST requests under /autotrader/v1.
Is the AutoTrader API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. AutoTrader calls use the same shared credit balance as every other ReefAPI engine.
Do I need an AutoTrader login or account?
No login to AutoTrader is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the AutoTrader data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the AutoTrader API use?
AutoTrader actions currently cost 1 credit per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call AutoTrader from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call autotrader actions with the same key, credit pool and JSON envelope used by normal REST requests.