# CarGurus Scraper 🚗 (`shahidirfan/cargurus-scraper`) Actor

Extract car listings from CarGurus with prices, makes, models, mileage, VINs, vehicle specifications, dealer details, locations, images, and listing URLs. Ideal for used car market research, price monitoring, competitor analysis, automotive leads, and AI datasets.

- **URL**: https://apify.com/shahidirfan/cargurus-scraper.md
- **Developed by:** [Shahid Irfan](https://apify.com/shahidirfan) (community)
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.80 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

### What does CarGurus Scraper do?

CarGurus Scraper collects vehicle listings from CarGurus search results pages and saves them as a clean, structured dataset. Give it a CarGurus search URL, or just a ZIP code with optional filters, and it returns prices, CarGurus deal ratings and Instant Market Value data, mileage, specs, photos, and dealer details for every listing it finds. The output is ready for spreadsheets, dashboards, price monitoring, and market research.

### Why use CarGurus Scraper?

- **Deal intelligence built in** - Every listing includes the CarGurus deal rating, deal score, Instant Market Value (IMV), and the dollar difference between the asking price and the IMV.
- **Rich vehicle detail** - Capture year, make, model, trim, body type, condition, mileage, engine, drivetrain, transmission, colors, fuel economy, safety rating, features, and more in one pass.
- **Dealer context** - Save seller name, type, city, state, ZIP code, phone, and distance from the searched location.
- **Flexible input** - Start from any CarGurus search URL, or build a search from a ZIP code and simple filters.
- **Clean data** - Empty fields are removed automatically, so your dataset does not contain always-null columns.
- **Automation ready** - Run on demand or on a schedule, export to JSON, CSV, or Excel, and connect results to your own tools.

### What data can you extract from CarGurus?

| Field                                                                                      | Description                                              |
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `listingId`                                                                                | CarGurus listing identifier                              |
| `vin`                                                                                      | Vehicle identification number                            |
| `title`                                                                                    | Full listing title with year, make, model, and trim      |
| `year`, `make`, `model`, `trim`, `bodyType`                                                | Vehicle identity and body style                          |
| `condition`                                                                                | USED, NEW, or CPO                                        |
| `dealRating`                                                                               | CarGurus deal rating such as GREAT_PRICE or GOOD_PRICE   |
| `dealScore`                                                                                | CarGurus internal deal ranking score                     |
| `price`, `totalPrice`                                                                      | Asking price and price including dealer fees             |
| `imvPrice`                                                                                 | CarGurus Instant Market Value                            |
| `priceDifferential`                                                                        | Dollars below (positive) or above (negative) the IMV     |
| `mileage`, `mileageUnit`                                                                   | Odometer reading and unit                                |
| `exteriorColor`, `interiorColor`                                                           | Color names and normalized values                        |
| `transmission`, `drivetrain`, `engine`                                                     | Drivetrain and mechanical specs                          |
| `fuelType` and fuel economy                                                                | Fuel type plus city, highway, and combined economy       |
| `safetyRating`, `daysOnMarket`                                                             | NHTSA safety rating and days the listing has been online |
| `distanceMiles`                                                                            | Distance from the searched ZIP code                      |
| `primaryImage`, `imageCount`                                                               | Lead photo and number of photos                          |
| `features`                                                                                 | List of notable vehicle features                         |
| `sellerName`, `sellerType`, `sellerCity`, `sellerState`, `sellerPostalCode`, `sellerPhone` | Dealer details                                           |
| `listingUrl`                                                                               | Direct link to the listing on CarGurus                   |

### How to use CarGurus Scraper

1. Open the Actor on Apify Store.
2. Enter a CarGurus search URL, or a ZIP code with optional filters.
3. Set the maximum number of listings and pages.
4. Run the Actor.
5. Download the dataset as JSON, CSV, or Excel, or connect it to your workflow.

If you provide a CarGurus search URL, it is used exactly as-is and the location and filter fields are ignored. If you provide a location instead, the Actor builds the search from your ZIP code, filters, and sort settings.

### Input Parameters

| Parameter                   | Type    | Required | Default      | Description                                                                                       |
| --------------------------- | ------- | -------- | ------------ | ------------------------------------------------------------------------------------------------- |
| `startUrl`                  | String  | No       | -            | A full CarGurus search results URL. Takes priority over all filter fields                         |
| `location`                  | String  | No       | `10001`      | US ZIP code to search around, used when no start URL is provided                                  |
| `make`                      | String  | No       | -            | Vehicle make name, for example Toyota                                                             |
| `model`                     | String  | No       | -            | Vehicle model name, for example RAV4                                                              |
| `condition`                 | String  | No       | `any`        | `any`, `used`, `new`, or `certified`                                                              |
| `distance`                  | Integer | No       | `50`         | Search radius in miles                                                                            |
| `minPrice` / `maxPrice`     | Integer | No       | -            | Lower and upper price bounds in USD                                                               |
| `minMileage` / `maxMileage` | Integer | No       | -            | Lower and upper mileage bounds                                                                    |
| `minYear` / `maxYear`       | Integer | No       | -            | Earliest and latest model years                                                                   |
| `sortType`                  | String  | No       | `BEST_MATCH` | Sort field: best match, deal score, price, mileage, distance, newest car year, or newest listings |
| `sortDirection`             | String  | No       | `ASC`        | `ASC` or `DESC`                                                                                   |
| `results_wanted`            | Integer | No       | `20`         | Maximum number of listings to save                                                                |
| `max_pages`                 | Integer | No       | `10`         | Safety cap on the number of search pages to visit                                                 |
| `proxyConfiguration`        | Object  | No       | Apify Proxy  | Proxy settings, Apify Proxy recommended                                                           |

### Output Data

| Field               | Type   | Description                                     |
| ------------------- | ------ | ----------------------------------------------- |
| `listingId`         | Number | CarGurus listing identifier                     |
| `vin`               | String | Vehicle identification number                   |
| `title`             | String | Full listing title                              |
| `year`              | Number | Model year                                      |
| `make`              | String | Vehicle manufacturer                            |
| `model`             | String | Vehicle model                                   |
| `trim`              | String | Vehicle trim                                    |
| `bodyType`          | String | Body style                                      |
| `condition`         | String | USED, NEW, or CPO                               |
| `dealRating`        | String | CarGurus deal rating                            |
| `dealScore`         | Number | Deal ranking score                              |
| `price`             | Number | Asking price in USD                             |
| `totalPrice`        | Number | Price including dealer fees                     |
| `imvPrice`          | Number | CarGurus Instant Market Value                   |
| `priceDifferential` | Number | Difference versus IMV, positive means below IMV |
| `mileage`           | Number | Odometer reading                                |
| `mileageUnit`       | String | Mileage unit                                    |
| `exteriorColor`     | String | Exterior color                                  |
| `transmission`      | String | Transmission type                               |
| `drivetrain`        | String | Drivetrain                                      |
| `engine`            | String | Engine description                              |
| `fuelType`          | String | Fuel type                                       |
| `daysOnMarket`      | Number | Days the listing has been online                |
| `distanceMiles`     | Number | Distance from the searched ZIP code             |
| `primaryImage`      | String | Primary photo URL                               |
| `sellerName`        | String | Dealer name                                     |
| `sellerCity`        | String | Dealer city                                     |
| `sellerState`       | String | Dealer state                                    |
| `listingUrl`        | String | Direct listing URL                              |
| `scrapedAt`         | String | ISO timestamp of collection                     |

Empty fields are removed from each record, so only fields with values appear in the dataset.

### Usage Examples

#### Scrape from a CarGurus search URL

Collect listings from a prepared CarGurus search, such as Acura cars within 10 miles of ZIP 10001:

```json
{
    "startUrl": "https://www.cargurus.com/search?distance=10&sortDirection=ASC&sortType=BEST_MATCH&zip=10001&makeModelTrimPaths=m4&page=1",
    "results_wanted": 100,
    "max_pages": 5
}
```

#### Build a search from a ZIP code and filters

Search for used sedans priced between 15,000 and 30,000 USD near ZIP 90210, sorted by price:

```json
{
    "location": "90210",
    "condition": "used",
    "minPrice": 15000,
    "maxPrice": 30000,
    "sortType": "PRICE",
    "sortDirection": "ASC",
    "results_wanted": 50,
    "max_pages": 5
}
```

#### Search a specific make and model

Collect Toyota RAV4 listings near ZIP 78701:

```json
{
    "location": "78701",
    "make": "Toyota",
    "model": "RAV4",
    "distance": 50,
    "results_wanted": 50,
    "max_pages": 5
}
```

#### Track certified pre-owned inventory

Collect certified pre-owned listings near ZIP 10001:

```json
{
    "location": "10001",
    "condition": "certified",
    "distance": 100,
    "results_wanted": 40,
    "max_pages": 4
}
```

### Sample Output

```json
{
    "listingId": 458585614,
    "vin": "5J8YE1H0XSL802783",
    "title": "2025 Acura MDX",
    "year": 2025,
    "make": "Acura",
    "model": "MDX",
    "trim": "SH-AWD with A-SPEC Package",
    "bodyType": "SUV / Crossover",
    "condition": "USED",
    "dealRating": "GOOD_PRICE",
    "dealScore": 1.7356389,
    "price": 46490,
    "totalPrice": 46665,
    "imvPrice": 47461,
    "priceDifferential": 971,
    "currency": "USD",
    "mileage": 12835,
    "mileageUnit": "MILES",
    "exteriorColor": "Silver",
    "normalizedExteriorColor": "SILVER",
    "interiorColor": "Black (Ebony)",
    "transmission": "Automatic",
    "drivetrain": "All-Wheel Drive",
    "engine": "290 hp 3.5L V6",
    "doors": "4 doors",
    "fuelType": "Gasoline",
    "cityFuelEconomy": 19,
    "highwayFuelEconomy": 25,
    "combinedFuelEconomy": 21.7,
    "fuelEconomyUnit": "MPG",
    "daysOnMarket": 36,
    "distanceMiles": 5.450355,
    "primaryImage": "https://static.cargurus.com/images/forsale/2026/10/16/04/40/2025_acura_mdx-pic-4066649105097917600-1024x768.jpeg",
    "imageCount": 45,
    "features": ["Leather Seats", "Sunroof/Moonroof", "Navigation System", "Backup Camera"],
    "sellerName": "Heights Nissan",
    "sellerId": 1736983,
    "sellerCity": "Jackson Heights",
    "sellerState": "NY",
    "sellerPostalCode": "11372",
    "sellerPhone": "(718) 568-7217",
    "stockNumber": "NU928",
    "listingUrl": "https://www.cargurus.com/details/458585614",
    "scrapedAt": "2026-10-17T16:22:22.270Z"
}
```

### Tips for Best Results

- Paste a CarGurus search URL you built in your browser to reuse exactly the same filters, sort, and location.
- Use a ZIP code in `location` for accurate distance and inventory results.
- Start with a small `results_wanted` value to confirm the fields you need before running a large job.
- Increase `max_pages` for larger datasets; each page returns roughly 20 to 24 listings.
- Use the `priceDifferential` field to surface the best deals, for example listings where the price is below the Instant Market Value.
- Keep Apify Proxy enabled for reliable, uninterrupted runs.
- Schedule repeat runs to monitor price drops and days on market over time.

### Integrations

- **Google Sheets** - Export results to a spreadsheet for analysis.
- **Webhooks** - Trigger downstream workflows when a run finishes.
- **Make and Zapier** - Connect results to no-code automations.
- **API** - Access the dataset programmatically from your own systems.
- **CSV, Excel, JSON, XML** - Download the dataset in the format your tools require.

### Frequently Asked Questions

#### Can I export CarGurus data to CSV or Excel?

Yes. Apify datasets can be downloaded as CSV, Excel, JSON, XML, and other supported formats directly from the Actor run.

#### Can I scrape new, used, and certified pre-owned cars?

Yes. Use the `condition` input, or add the relevant filters in the CarGurus search URL you provide. Listings are labeled USED, NEW, or CPO in the output.

#### Can I run this Actor on a schedule?

Yes. You can schedule the Actor in Apify Console to refresh data hourly, daily, weekly, or at another interval, which is useful for price and inventory monitoring.

#### Do I need a CarGurus account or API key?

No. The Actor works with public CarGurus search results and does not require an account or API key.

#### How many listings can I collect?

You control the volume with `results_wanted` and `max_pages`. A single search page returns roughly 20 to 24 listings, and the Actor paginates until it reaches your limit or the last page.

#### Why are some fields missing on certain listings?

Some vehicles do not have every attribute published, such as fuel economy for some electric cars or safety ratings for unrated models. Fields without values are removed from the record instead of being saved as empty.

#### What should I do if a run returns no listings?

Check that your search URL or filters match actual inventory. If a search has no matching cars, the dataset is empty by design. Broaden the distance, price, or year filters and try again.

#### Is it legal to scrape CarGurus?

Scraping publicly available data can be legal, but you are responsible for complying with applicable laws, the CarGurus terms of service, and privacy rules in your jurisdiction.

### Support

For issues, feature requests, or custom Actor work, use the Issues tab on the Actor page or contact the developer through Apify.

### Legal Notice

This Actor is designed for legitimate data collection from publicly available sources. Users are responsible for using the data responsibly and complying with applicable laws and website terms.

# Actor input Schema

## `startUrl` (type: `string`):

A full CarGurus search results URL. When provided it is used exactly as-is and the location and filter fields below are ignored.

## `location` (type: `string`):

US ZIP code to search around, for example 10001. Used only when no CarGurus search URL is provided.

## `make` (type: `string`):

Vehicle make name, for example Toyota or Ford. Used only when no CarGurus search URL is provided.

## `model` (type: `string`):

Vehicle model name, for example Camry. Requires Make.

## `condition` (type: `string`):

Vehicle condition to include.

## `distance` (type: `integer`):

Distance in miles around the ZIP code.

## `minPrice` (type: `integer`):

Lowest listing price to include.

## `maxPrice` (type: `integer`):

Highest listing price to include.

## `minMileage` (type: `integer`):

Lowest odometer reading to include.

## `maxMileage` (type: `integer`):

Highest odometer reading to include.

## `minYear` (type: `integer`):

Earliest model year to include.

## `maxYear` (type: `integer`):

Latest model year to include.

## `sortType` (type: `string`):

Field used to order results.

## `sortDirection` (type: `string`):

Ascending or descending order.

## `results_wanted` (type: `integer`):

Maximum number of listings to save.

## `max_pages` (type: `integer`):

A safety cap on the number of search result pages to visit.

## `proxyConfiguration` (type: `object`):

Apify Proxy is recommended to avoid rate limits and blocks.

## Actor input object example

```json
{
  "location": "10001",
  "condition": "any",
  "distance": 50,
  "sortType": "BEST_MATCH",
  "sortDirection": "ASC",
  "results_wanted": 20,
  "max_pages": 10,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "location": "10001"
};

// Run the Actor and wait for it to finish
const run = await client.actor("shahidirfan/cargurus-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "location": "10001" }

# Run the Actor and wait for it to finish
run = client.actor("shahidirfan/cargurus-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "location": "10001"
}' |
apify call shahidirfan/cargurus-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,shahidirfan/cargurus-scraper"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/StxcELuODtIrwiiGf/builds/NthQM4DsmwIbucvOB/openapi.json