# Autotrader Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | active |
| **Method** | `GET` |
| **Endpoint** | `/v2/autotrader/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 2 credits per call |
| **Documentation** | https://www.piloterr.com/library/autotrader-search |

## Description

Search AutoTrader UK listings from a car-search URL and retrieve prices, specs, photos, seller info, and pagination via browser rendering.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/autotrader/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search used cars near W1F 8EB London

```json
{
  "results": [
    {
      "id": "202605302836426",
      "url": "https://www.autotrader.co.uk/car-details/202605302836426?journey=FEATURED_LISTING_JOURNEY&sort=relevance&twcs=true&searchId=3e386cc3-ab04-4465-bc96-dc0210e1801f&page=1&postcode=W1F%208EB&advertising-location=at_cars&fromsra&backLinkQueryParams=channel%3Dcars%26postcode%3DW1F%25208EB%26price_search_type%3Dtotal%26sort%3Drelevance%26page%3D1%26flrfc%3D1",
      "year": "2007 (07 reg)",
      "image": "https://m.atcdn.co.uk/a/media/w480/a75ac2d47f854a5ebaf070a25c3fe883.jpg",
      "price": "£2,500",
      "title": "Ford Focus1.8 Sport S 5dr",
      "images": [
        "https://m.atcdn.co.uk/a/media/w480/a75ac2d47f854a5ebaf070a25c3fe883.jpg",
        "https://m.atcdn.co.uk/a/media/w480/5f16246bee0e45d68ea4af8ee80b0d41.jpg"
      ],
      "mileage": "93,018 miles",
      "location": "Leicester",
      "subtitle": "1.8 Sport S 5dr",
      "seller_type": "dealer",
      "price_amount": 2500,
      "attention_grabber": "FULL SERVICE HISTORY+2 KEYS!!!"
    },
    {
      "id": "202606053041984",
      "url": "https://www.autotrader.co.uk/car-details/202606053041984?sort=relevance&twcs=true&searchId=3e386cc3-ab04-4465-bc96-dc0210e1801f&page=1&postcode=W1F%208EB&advertising-location=at_cars&fromsra&backLinkQueryParams=channel%3Dcars%26postcode%3DW1F%25208EB%26price_search_type%3Dtotal%26sort%3Drelevance%26page%3D1%26flrfc%3D1",
      "year": "2014 (14 reg)",
      "image": "https://m.atcdn.co.uk/a/media/w480/27178641a4bc471ebd9a6ea3d1d388fe.jpg",
      "price": "£3,795",
      "title": "Toyota Prius1.5 CVT 4dr",
      "images": [
        "https://m.atcdn.co.uk/a/media/w480/27178641a4bc471ebd9a6ea3d1d388fe.jpg",
        "https://m.atcdn.co.uk/a/media/w480/8834d446806d446c826019ae2ad60870.jpg"
      ],
      "mileage": "82,000 miles",
      "location": "Sidcup",
      "subtitle": "1.5 CVT 4dr",
      "seller_type": "dealer",
      "price_amount": 3795,
      "attention_grabber": "LOW MILEAGE|CHEAP INSURANCE"
    },
    {
      "id": "202605182478887",
      "url": "https://www.autotrader.co.uk/car-details/202605182478887?sort=relevance&twcs=true&searchId=3e386cc3-ab04-4465-bc96-dc0210e1801f&page=1&postcode=W1F%208EB&advertising-location=at_cars&fromsra&backLinkQueryParams=channel%3Dcars%26postcode%3DW1F%25208EB%26price_search_type%3Dtotal%26sort%3Drelevance%26page%3D1%26flrfc%3D1",
      "year": "2013 (13 reg)",
      "image": "https://m.atcdn.co.uk/a/media/w480/e8979c3380f24cf6a9a36a09206eafd4.jpg",
      "price": "£500",
      "title": "Ford Fiesta1.0T EcoBoost Zetec Euro 5 (s/s) 3dr",
      "images": [
        "https://m.atcdn.co.uk/a/media/w480/e8979c3380f24cf6a9a36a09206eafd4.jpg",
        "https://m.atcdn.co.uk/a/media/w480/216166463ac64cd8957e5ee02b4479d1.jpg"
      ],
      "mileage": "89,000 miles",
      "location": "Hughenden",
      "subtitle": "1.0T EcoBoost Zetec Euro 5 (s/s) 3dr",
      "seller_type": "dealer",
      "price_amount": 500,
      "attention_grabber": "Spares or repairs"
    }
  ],
  "pagination": {
    "next": 2,
    "current": 1,
    "next_url": "https://www.autotrader.co.uk/car-search?page=2",
    "per_page": 25,
    "total_count": 464626,
    "total_pages": 18586,
    "has_next_page": true
  }
}
```

## Documentation

## Overview
Extract vehicle listings from any AutoTrader UK search results page (`autotrader.co.uk/car-search`). Returns structured listings with price, mileage, year, location, seller type, photos, and pagination metadata.

AutoTrader UK search pages are React single-page applications (`sauron-search-results-app`). Listing cards (`data-testid="advertCard-*"`) are injected after JavaScript runs. A plain HTTP request only returns an empty HTML shell. Piloterr uses **website rendering** to load the page in a browser, wait for listings to appear, and extract structured JSON from the rendered DOM.

## Quickstart
```
GET https://api.piloterr.com/v2/autotrader/search?query=https://www.autotrader.co.uk/car-search?channel=cars&postcode=W1F%208EB&price_search_type=total&sort=relevance&page=1
```

Copy the full search URL from autotrader.co.uk. Append `?page=2` (or update the `page` query param) for pagination.

## Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Full AutoTrader UK `/car-search` URL |

## Response fields
| Field | Type | Description |
|---|---|---|
| `results` | array | List of vehicle listings |
| `results[].id` | string | AutoTrader advert ID |
| `results[].url` | string | Car details URL |
| `results[].title` | string \| null | Make and model title |
| `results[].subtitle` | string \| null | Trim / derivative |
| `results[].price` | string \| null | Formatted price (e.g. `£2,500`) |
| `results[].price_amount` | integer \| null | Numeric price in GBP |
| `results[].year` | string \| null | Registration year (e.g. `2007 (07 reg)`) |
| `results[].mileage` | string \| null | Mileage string |
| `results[].location` | string \| null | Seller location |
| `results[].seller_type` | string \| null | `dealer` or `private` |
| `results[].attention_grabber` | string \| null | Dealer highlight text |
| `results[].image` | string \| null | Main thumbnail URL |
| `results[].images` | array | Gallery image URLs |
| `pagination.current` | integer | Current page number |
| `pagination.next` | integer \| null | Next page number |
| `pagination.next_url` | string \| null | Next page URL |
| `pagination.total_pages` | integer | Total pages |
| `pagination.total_count` | integer | Total matching listings |
| `pagination.per_page` | integer | Results on this page |
| `pagination.has_next_page` | boolean | Whether a next page exists |

## Notes
- Targets **autotrader.co.uk** (UK). US listings on autotrader.com are not supported.
- Filters in the URL (`postcode`, `make`, `price`, `sort`, etc.) are respected.
- Some cards may return partial data depending on listing type.
- Pass a car details URL to the AutoTrader Ad endpoint for full specs, description, and seller contact.

## Main use cases
- Monitor used car inventory and pricing across UK postcodes
- Build dealer lead lists with price, mileage, and location
- Feed automotive analytics pipelines with live market data
- Track pagination across AutoTrader search result pages