# CarGurus Deal Rating & Dealer Inventory Scraper (`vexaloom-labs/cargurus-deal-rating-and-dealer-inventory-scraper`) Actor

Search CarGurus by make, model, ZIP code and price range, fetch one listing by ID, or scrape a pasted search URL, with deal rating, mileage and dealer details for every listing.

- **URL**: https://apify.com/vexaloom-labs/cargurus-deal-rating-and-dealer-inventory-scraper.md
- **Developed by:** [vexaloom-labs](https://apify.com/vexaloom-labs) (community)
- **Categories:** Automation, Lead generation, E-commerce
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## CarGurus Deal Rating & Dealer Inventory Scraper

CarGurus rates every listing against its Instant Market Value (IMV) and labels it from Great Deal down to Overpriced. This actor collects that rating, the IMV, the numeric deal score, the asking price, mileage, specs, dealer contact details and photos — by make/model/ZIP search, by a single listing ID, or from a CarGurus search URL you paste in.

### Modes

- **Search** — build a query from make, model, ZIP, radius, condition, deal rating, body style, fuel, transmission, drivetrain, price, mileage, photo and price-drop filters, and walk every result page.
- **Single listing** — fetch one listing by its CarGurus ID (for example `464410035` from `/details/464410035`).
- **Paste a URL** — paste a CarGurus search-results URL (old `searchResults.action` links are accepted) or a listing URL.

### What you get per listing

| Field | Description |
| --- | --- |
| `listingId` | CarGurus listing ID. |
| `url` | Direct `cargurus.com/details/<id>` link. |
| `title` | Year, make, model and trim as shown by CarGurus. |
| `vin`, `stockNumber` | VIN and dealer stock number when published. |
| `year`, `make`, `model`, `trim`, `bodyType` | Vehicle identity. |
| `price`, `pricePlusFees` | Asking price and the advertised price including disclosed fees. |
| `expectedPrice` | CarGurus Instant Market Value (IMV) for this car. |
| `priceDifference` | Price minus IMV (positive means above market). |
| `dealRating`, `dealRatingCode`, `dealScore` | Human label, raw CarGurus code and numeric deal score. |
| `mileage`, `condition` | Odometer reading and New / Used / Certified Pre-Owned. |
| `exteriorColor`, `interiorColor` | Published colors. |
| `transmission`, `driveType`, `engine`, `fuelType` | Powertrain and engine details. |
| `mpgCity`, `mpgHighway`, `mpgCombined` | EPA-style fuel economy when published. |
| `doors`, `options`, `tags`, `safetyRating` | Body details, installed options, badges and NHTSA rating. |
| `dealerName`, `dealerId`, `dealerType` | Selling dealer identity. |
| `dealerCity`, `dealerState`, `dealerPostalCode`, `dealerPhone` | Dealer location and phone. |
| `dealerWebsite`, `dealerRating`, `dealerReviewCount` | Dealer site and review summary (single-listing mode). |
| `dealerStreet`, `dealerLatitude`, `dealerLongitude`, `dealerLogoUrl` | More dealer detail (single-listing mode). |
| `distanceMiles`, `daysOnMarket` | Distance from the search ZIP and days listed. |
| `photoCount`, `primaryPhotoUrl`, `images` | Photo count, main photo and every photo (single-listing mode). |
| `accidentCount`, `ownerCount`, `vehicleHistoryReport` | Vehicle-history summary (single-listing mode). |
| `siteName`, `scrapedAt`, `recordType` | Source and capture metadata. |

Fields the source does not publish for a listing are omitted from that record — never filled with `null` or a placeholder.

### Input

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `mode` | Select | `search` | `search`, `byListingId` or `byUrl`. |
| `make` | Select | – | Manufacturer (all makes CarGurus lists). |
| `model` | Text | – | Model name, e.g. `Camry`. Empty means every model. |
| `condition` | Select | Any | New, Used or Certified Pre-Owned. Certified searches need a make. |
| `sortBy` | Select | `best_deal` | Best deal/match, price, mileage, year or distance. |
| `zipCode` | Text | – | 5-digit US ZIP code. |
| `distanceMiles` | Select | 50 | Search radius: 10–500 miles. |
| `minPrice`, `maxPrice` | Integer | – | Price range in USD. |
| `maxMileage` | Integer | – | Odometer ceiling. |
| `dealRating` | Select | Any | Great Deal, Good Deal, Fair Deal, High Price, Overpriced, No Price Analysis or Uncertain. |
| `bodyType` | Select | Any | Coupe, Convertible, Hatchback, Minivan, Pickup, Sedan, SUV/Crossover, Van, Wagon. |
| `fuelType` | Select | Any | Gasoline, Hybrid, Electric, Diesel, Biodiesel or Flex Fuel. |
| `transmission` | Select | Any | Automatic or Manual. |
| `drivetrain` | Select | Any | AWD, FWD, RWD, 4WD or 4X2. |
| `onlyWithPhotos` | Boolean | false | Skip listings with no photos. |
| `onlyPriceDrops` | Boolean | false | Only recent price drops. |
| `listingId` | Text | – | Listing ID for `byListingId`. |
| `url` | Text | – | Search or listing URL for `byUrl`. |
| `maxItems` | Integer | 5 | Maximum records to emit (1–1000). |

#### Examples

Used Toyota Camry near New York:

```json
{
  "mode": "search",
  "make": "Toyota",
  "model": "Camry",
  "condition": "Used",
  "zipCode": "10001",
  "distanceMiles": 50,
  "maxPrice": 30000,
  "maxItems": 50
}
```

Great-deal hybrid SUVs with all-wheel drive and photos:

```json
{
  "mode": "search",
  "make": "Toyota",
  "zipCode": "10001",
  "dealRating": "GREAT_PRICE",
  "bodyType": "SUV / Crossover",
  "fuelType": "Hybrid",
  "drivetrain": "All-Wheel Drive",
  "onlyWithPhotos": true,
  "maxItems": 25
}
```

One listing by ID:

```json
{"mode": "byListingId", "listingId": "464410035", "maxItems": 1}
```

A pasted search URL:

```json
{"mode": "byUrl", "url": "https://www.cargurus.com/Cars/l-Used-Toyota-Camry-Raleigh-d292_L25152", "maxItems": 100}
```

### Data source and reliability

CarGurus renders its search results from a public Remix loader payload. The actor reads that payload through Google's live translate mirror (no account or cookies) and rotates exits/languages, with an Apify unblocker fallback for DataDome-protected detail pages. You do not need to supply cookies, API keys or proxy settings; the actor selects its route automatically.

### Use cases

- **Car shoppers** compare deal ratings and IMV on a shortlist near a ZIP code.
- **Dealers** monitor competitors' inventory, pricing and days on market.
- **Pricing analysts** track how deal scores and price differences move by model and region.
- **Lead generation** collects dealer name, phone and location alongside active listings.
- **Fleet buyers** screen by mileage, body style, fuel and drivetrain.

### FAQ

**Does this need a CarGurus login?**
No. It reads publicly visible listing data and never asks for an account.

**What does `dealRating` mean?**
CarGurus compares a car's price with its Instant Market Value. Great Deal and Good Deal are below IMV, Fair Deal is close, High Price and Overpriced are above it. `dealRatingCode` keeps CarGurus's raw value.

**Why is a field missing on some records?**
Not every listing publishes a VIN, MPG, dealer rating or full photo set. Missing fields are omitted, not filled with a placeholder.

**Can I filter by model year?**
Not yet: CarGurus's current search loader ignores year-range parameters. Use `minPrice`/`maxPrice` and sort by model year, or paste a URL with the site's own year filter.

**Can I scrape certified pre-owned cars?**
Yes, with a make selected. CarGurus exposes certified inventory through its make pages; a make-less certified search is not available.

**How many results can I get?**
Up to 1,000 per run via `maxItems`. Large runs walk result pages until `maxItems` or the source ends. CarGurus shows an approximate national total that is not filter-specific, so result counts in the dataset are authoritative.

**Is this affiliated with CarGurus?**
No. This is an independent tool and is not affiliated with, endorsed by, or sponsored by CarGurus.

### Legacy inputs

Saved tasks that still send `zip`, `searchUrl`, `startUrl`, `startUrls`, `maxResults`, `carCondition`, `makeName`, `modelName`, `listingID` or `sort` keep working: the actor maps them in code to the current fields.

# Actor input Schema

## `mode` (type: `string`):

How to find listings.

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

Vehicle manufacturer to search. Leave empty to search every make near the ZIP code.

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

Model name, e.g. Camry or F-150. Leave empty for every model of the chosen make.

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

New, used or certified pre-owned inventory. Certified searches require a make.

## `sortBy` (type: `string`):

Result ordering.

## `zipCode` (type: `string`):

5-digit US ZIP code used to center the search, e.g. 10001.

## `distanceMiles` (type: `string`):

How far from the ZIP code to search.

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

Minimum listing price in US dollars.

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

Maximum listing price in US dollars.

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

Maximum odometer reading in miles.

## `dealRating` (type: `string`):

Only return listings CarGurus rates at this level. Leave empty for every rating.

## `bodyType` (type: `string`):

Limit results to one body style.

## `fuelType` (type: `string`):

Limit results to one fuel type.

## `transmission` (type: `string`):

Limit results by transmission.

## `drivetrain` (type: `string`):

Limit results by driven wheels.

## `onlyWithPhotos` (type: `boolean`):

Skip listings that have no photos.

## `onlyPriceDrops` (type: `boolean`):

Only return listings whose price dropped recently.

## `listingId` (type: `string`):

CarGurus listing ID from a listing URL or the /details/<id> page.

## `url` (type: `string`):

A CarGurus search results URL or listing URL. Old action-style search URLs are accepted too.

## `maxItems` (type: `integer`):

Maximum number of listings to emit.

## Actor input object example

```json
{
  "mode": "byListingId",
  "make": "Toyota",
  "condition": "",
  "sortBy": "best_deal",
  "zipCode": "10001",
  "distanceMiles": "50",
  "dealRating": "",
  "bodyType": "",
  "fuelType": "",
  "transmission": "",
  "drivetrain": "",
  "onlyWithPhotos": false,
  "onlyPriceDrops": false,
  "listingId": "464410035",
  "maxItems": 1
}
```

# Actor output Schema

## `records` (type: `string`):

Dataset containing all scraped CarGurus car listings.

# 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 = {
    "mode": "byListingId",
    "make": "Toyota",
    "condition": "",
    "sortBy": "best_deal",
    "zipCode": "10001",
    "distanceMiles": "50",
    "onlyWithPhotos": false,
    "onlyPriceDrops": false,
    "listingId": "464410035",
    "maxItems": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("vexaloom-labs/cargurus-deal-rating-and-dealer-inventory-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 = {
    "mode": "byListingId",
    "make": "Toyota",
    "condition": "",
    "sortBy": "best_deal",
    "zipCode": "10001",
    "distanceMiles": "50",
    "onlyWithPhotos": False,
    "onlyPriceDrops": False,
    "listingId": "464410035",
    "maxItems": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("vexaloom-labs/cargurus-deal-rating-and-dealer-inventory-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 '{
  "mode": "byListingId",
  "make": "Toyota",
  "condition": "",
  "sortBy": "best_deal",
  "zipCode": "10001",
  "distanceMiles": "50",
  "onlyWithPhotos": false,
  "onlyPriceDrops": false,
  "listingId": "464410035",
  "maxItems": 1
}' |
apify call vexaloom-labs/cargurus-deal-rating-and-dealer-inventory-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vexaloom-labs/cargurus-deal-rating-and-dealer-inventory-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/sqGioneiW24skxYGj/builds/qABQVwWb0mhDOag9w/openapi.json
