# CarGurus Search API Documentation

Search US CarGurus listings with make/model paths, price range, distance and sorting. Every listing carries the CarGurus deal rating, the price against the CarGurus Instant Market Value where the listing publishes it, mileage, engine, transmission, drivetrain, colours, images, the equipment list and the seller record. Pagination follows the CarGurus page counter; a page past the last result returns an empty listings array and has_more false.

- **Documentation:** [https://scrappa.co/docs/cargurus-api/cargurus_search](https://scrappa.co/docs/cargurus-api/cargurus_search)
- **API group:** CarGurus API
- **Endpoint:** `GET https://scrappa.co/api/cargurus/v1/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_model_trim_paths` | string | No | CarGurus make/model paths, for example m26/d126 for GMC Suburban. Several paths can be comma-separated. |
| `price_min` | integer | No | Optional non-negative minimum price in US dollars. |
| `price_max` | integer | No | Optional non-negative maximum price in US dollars. Must be greater than or equal to price_min. |
| `distance` | integer | No | Search radius in miles, 1 to 50000. Defaults to 50000 (nationwide). |
| `sort` | string | No | best_match, deal_score, price, mileage, distance or date. Defaults to best_match. |
| `sort_direction` | string | No | asc or desc. Defaults to asc. |
| `page` | integer | No | Result page, starting at 1. Defaults to 1. |

## Example request

```bash
#!/bin/bash

curl -X GET \
    -H "x-api-key: YOUR_API_KEY_HERE" \
    "https://scrappa.co/api/cargurus/v1/search?make_model_trim_paths=m26%2Fd126&distance=50000&sort=best_match"
```

## Example response

```json
{
    "success": true,
    "data": {
        "listings": [
            {
                "listing_id": 457265465,
                "listing_title": "1993 GMC Suburban",
                "listing_url": "https://www.cargurus.com/details/457265465",
                "vin": "1GKGK26N8PJ702664",
                "year": 1993,
                "make": "GMC",
                "model": "Suburban",
                "price": {
                    "amount": 14995,
                    "currency": "USD",
                    "localized": "$14,995",
                    "rating": "NA"
                },
                "mileage": {
                    "value": 100474,
                    "unit": "MILES",
                    "localized": "100,474"
                },
                "seller_type": "DEALER"
            }
        ],
        "pagination": {
            "page": 1,
            "page_size": 20,
            "page_count": 1,
            "total": 20,
            "has_more": false
        }
    },
    "meta": {
        "endpoint_family": "search",
        "market": "US"
    }
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A public parameter or range is invalid. This response is not billable. |
| 503 | Unexpected Upstream Response | CarGurus returned an unrecognized response shape. This response is not billable. |
| 503 | Upstream 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)