Blog / API guides

AutoTrader UK API: Get Used Car Listings as JSON

20 Aug 2026Perceptlayer6 min read

You can get AutoTrader UK listings as JSON without writing a scraper: call GET /v1/autotrader-uk/search with a UK postcode and an X-API-Key header, and you get listings with price, title, distance, images and a total result count. Each call costs 1 credit, and failed calls cost nothing. This guide shows the request, the parameters, a recorded response and the cost of paging through a whole search.

Is there an official AutoTrader UK API?

We can't point you to one. We haven't verified what Auto Trader offers directly, so if you're a dealer managing your own adverts, ask Auto Trader about its partner options.

To read public used-car search results for a postcode, the options are writing and maintaining a scraper, or calling an API that returns the listings as JSON. This article covers the second one.

What does the AutoTrader UK API return?

The AutoTrader UK API in the Perceptlayer catalogue has six endpoints, all GET, all 1 credit per call. The catalogue holds 248 websites and 1,659 endpoints in total, all returning JSON, and this is the AutoTrader UK API in the Cars area.

A typical flow: search to find candidates, then listing with an advert_id for one advert's detail. Use facets to see how a search breaks down, and dealer-listings to read one dealer's stock.

How do you run a used car search?

Send a GET to /v1/autotrader-uk/search with a postcode and your key. Keys start with sk_live_ and go in the X-API-Key header; the authentication docs cover the query-parameter option. Get a free API key if you don't have one.

curl "https://api.perceptlayer.com/v1/autotrader-uk/search?postcode=SW1A1AA&price_search_type=total&make=BMW&sort=relevance&page=1" \
  -H "X-API-Key: $API_KEY"

This searches BMWs around SW1A1AA and sorts by relevance. price_search_type=total asks for the total price rather than a monthly one. Only postcode is required, so you can drop everything else and get an unfiltered search.

Which parameters does the search endpoint take?

The search endpoint takes one required parameter and seventeen optional ones. Types and allowed values below are as documented; nothing else about them is documented, so check the Search endpoint page or try values in the playground.

dealer-listings takes the same filters plus a required retailer_id.

What does a search response look like?

A search response has three parts: data.listings, an array of adverts; data.pagination; and a meta block. This is a trimmed excerpt of a real recorded response for the BMW request above, with … marking what was cut.

{
  "success": true,
  "data": {
    "listings": [
      {
        "advert_id": "202610227244889",
        "type": "NATURAL_LISTING",
        "title": "BMW X5",
        "sub_title": "3.0d SE Exclusive Edition Auto 4WD Euro 4 5dr",
        "price": {
          "amount": 2700,
          "currency": "GBP",
          "display": "£2,700"
        },
        "vehicle_location": "Crawley (27 miles)",
        "distance": { "value": 27, "unit": "miles" },
        "number_of_images": 16,
        "seller_type": "PRIVATE",
        "position": 1,
        "tracking_context": {
          "price": 2700,
          "make": "BMW",
          "model": "X5",
          "year": 2005,
          "condition": "used",
          "price_indicator": "NOANALYSIS"
        }
      },
      …
    ],
    "pagination": {
      "page": 1,
      "page_count": 2146,
      "total_results": 42916,
      "has_more": true
    }
  },
  "meta": {
    "duration_ms": 1129,
    "endpoint_family": "search"
  }
}

What do the main fields mean?

The fields you'll use most are in the table below. Meanings are read from the recorded values, not from separate documentation.

Mileage, fuel type and the like aren't in the excerpt, so this guide doesn't describe them. Run a listing call in the playground on the AutoTrader UK API page to see what an individual advert carries. For which fields matter when you analyse prices, see Used Car Listing Data: Fields for Price Analysis.

How do you narrow a search or list what's available?

Add filters to cut a search down, or call facets to see how results break down before you filter. Both are the same 1 credit per call, and a narrower search means fewer pages to fetch. Here is a filtered search for automatic cars under £10,000 from trade sellers, newest first.

curl -G "https://api.perceptlayer.com/v1/autotrader-uk/search" \
  -d "postcode=SW1A1AA" \
  -d "make=BMW" \
  -d "transmission=Automatic" \
  -d "seller_type=trade" \
  -d "max_price=10000" \
  -d "sort=most_recent" \
  -H "X-API-Key: $API_KEY"

transmission is a free-text string, so check the accepted values against the facets before relying on one.

For the breakdown, facets takes a facets[] list. Allowed values include make, model, body_type, colour, fuel_type, transmission, seller_type, price, mileage and year_manufactured, among others.

curl -G "https://api.perceptlayer.com/v1/autotrader-uk/facets" \
  -d "postcode=SW1A1AA" \
  -d "facets[]=make" \
  -d "facets[]=fuel_type" \
  -H "X-API-Key: $API_KEY"

We haven't recorded a facets response for this article, so it doesn't quote one. The Facets endpoint page has a playground. The taxonomy endpoint, which takes postcode and an optional make, is the place to look when you need valid make and model values.

How do you page through all the results?

Read data.pagination on every response and keep going while has_more is true. In the recorded search, page_count was 2,146 and total_results 42,916, so one call returns a page of a much larger set. Each page is a separate call at 1 credit.

import os
import time
import requests

URL = "https://api.perceptlayer.com/v1/autotrader-uk/search"
HEADERS = {"X-API-Key": os.environ["API_KEY"]}
params = {"postcode": "SW1A1AA", "make": "BMW", "sort": "price_asc", "page": 1}
max_pages = 5  # cap spend while you test

listings = []
while params["page"] <= max_pages:
    resp = requests.get(URL, params=params, headers=HEADERS, timeout=30)
    if resp.status_code in (429, 503):
        time.sleep(int(resp.headers.get("Retry-After", "5")))
        continue
    resp.raise_for_status()
    data = resp.json()["data"]
    listings.extend(data["listings"])
    if not data["pagination"]["has_more"]:
        break
    params["page"] += 1

print(len(listings), "listings")

The Retry-After header carries the seconds to wait on a 429 or 503. For safer loops see Paginate a Web Data API in Python, and for what a timed-out request can mean for billing, Retry Web API Calls Without Paying Twice.

What does it cost?

Every endpoint here costs 1 credit per successful call. A failed call costs nothing and returns X-Credits-Used: 0; every successful response carries X-Credits-Used and X-Credits-Remaining. The free tier gives you 1,000 credits a month after you verify an email address, with no credit card.

Worked examples, using the recorded search:

• Reading all 2,146 pages of that BMW search once: 2,146 pages × 1 credit = 2,146 credits. That is more than the 1,000 free credits, so filter first.
• Checking 200 adverts with listing after a search: 200 calls × 1 credit = 200 credits.
• A daily 5-page search for one postcode over 30 days: 30 × 5 × 1 credit = 150 credits.

Purchased credits last 12 months, with no subscription. The credits docs explain billing, and pricing shows what credits cost. Rate limits are per account; free accounts get 1 request a second, so a page loop needs the Retry-After handling above. The rate limits docs and errors docs cover the rest.

What should you build next?

Start with one postcode and one make, store advert_id with price.amount and a timestamp on each run, and compare runs. That gives you price movement for a model without scraping anything. If you're building an agent instead, the same endpoints are callable as tools over MCP; see the AI agents docs.

For other UK listings, see the Rightmove API guide. To try this call now, get a free API key and run the search in the playground on the AutoTrader UK API page.

autotraderused carscar listingsukcars api