# heycar Car Search API Documentation

Search car listings on heycar, now Drive (drive.co.uk), the UK car marketplace. Filter by make, model, price in GBP, mileage in miles, fuel type, body type and gearbox, and sort by price, year, mileage or distance. Each listing has the title, make, model, variant, price with currency, year, mileage, registration, body type, fuel type, gearbox, colour, engine size, power, CO2, images, dealer, location, timestamps (ISO 8601, UTC) and the public web url. Page with the 0-based page and size parameters. UK stock only (GBP). A valid filter with no match is a successful empty page.

- **Documentation:** [https://scrappa.co/docs/heycar-api/heycar_search](https://scrappa.co/docs/heycar-api/heycar_search)
- **API group:** heycar API
- **Endpoint:** `GET https://scrappa.co/api/heycar/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `make` | string | No | Make slug, lowercase. Example: volkswagen. Use mercedes_benz (with underscore) for Mercedes-Benz. |
| `model` | string | No | Model slug with the make prefix. Example: volkswagen-golf. |
| `page` | integer | No | 0-based page number, 0 to 399. Defaults to 0. |
| `size` | integer | No | Listings per page, 1 to 50. Defaults to 20. |
| `sort` | string | No | Sort order: price-asc, price-desc, year-desc, mileage-asc, date-active-desc, relevance-desc or distance-asc. Omit for the default order. |
| `price_min` | integer | No | Minimum price in GBP, whole pounds. |
| `price_max` | integer | No | Maximum price in GBP, whole pounds. |
| `mileage_max` | integer | No | Maximum mileage in miles. |
| `fuel_type` | string | No | One of petrol, diesel, hybrid, electric. |
| `body_type` | string | No | One of suv, saloon, estate, convertible, coupe, hatchback. |
| `gearbox` | string | No | One of automatic, manual, semiauto. |
| `lat` | number | No | Latitude. Send with lon and sort=distance-asc to order by distance and exclude far listings. |
| `lon` | number | No | Longitude. Send with lat. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/heycar/search?make=volkswagen&model=volkswagen-golf&page=0&size=20"
```

## Example response

```json
{
    "success": true,
    "data": {
        "listings": [
            {
                "id": "16731596",
                "heycar_id": "volkswagen-golf-2016-14-tsi-125-match-edition-5dr-dsg-b52b7c37",
                "title": "Volkswagen Golf 1.4 TSI 125 Match Edition 5dr DSG",
                "make": {
                    "id": "volkswagen",
                    "label": "Volkswagen"
                },
                "model": {
                    "id": "volkswagen-golf",
                    "label": "Golf"
                },
                "variant": "1.4 TSI 125 Match Edition 5dr DSG",
                "price": 13499,
                "currency": "GBP",
                "is_vat_included": true,
                "year": 2016,
                "mileage": 15651,
                "registration": "SK66MDO",
                "stock_condition": "used",
                "previous_owners": 2,
                "body_type": "hatchback",
                "fuel_type": "petrol",
                "gearbox": "semiauto",
                "color": "blue",
                "doors": 5,
                "seats": 5,
                "engine_size": 1.4,
                "bhp": 123.4,
                "co2_g_km": 116,
                "first_registration_date": "2016-09-14",
                "is_ulez_compliant": false,
                "image_count": 35,
                "images": [
                    "https://cdn.uk.prod.group-mobility-trader.com/images/cas/811d30f1406ca1d31dbe202d3888873e/e8ef682826ac1c09a1bd3fd3c33e363c.jpg"
                ],
                "dealer": {
                    "id": "7237",
                    "name": "Car Deal Warehouse Superstore Newbridge",
                    "city": "Newbridge"
                },
                "location": {
                    "postcode": "EH288TH",
                    "latitude": 55.942214,
                    "longitude": -3.405555
                },
                "created_at": "2026-10-07T06:30:41Z",
                "last_updated_at": "2026-10-15T01:43:15Z",
                "active_at": "2026-10-07",
                "url": "https://drive.co.uk/auto/volkswagen-golf-2016-14-tsi-125-match-edition-5dr-dsg-b52b7c37"
            }
        ],
        "total": 2087,
        "page": 0,
        "size": 20,
        "total_pages": 696,
        "has_more": true,
        "next_page": 1
    },
    "meta": {
        "endpoint_family": "search",
        "billable": true
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A query parameter is missing or invalid. This response is not billable. |
| 502 | Invalid Source Response | The upstream answered with a shape that no longer matches the documented contract. This response is not billable. |
| 503 | Service Unavailable | The upstream service is temporarily unavailable. Please retry shortly. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)