# KBB Cars for Sale Scraper - Kelley Blue Book Listings (`lulzasaur/kbb-scraper`) Actor

Scrape used and new car listings from Kelley Blue Book (KBB). Get price, mileage, VIN, dealer info, deal rating, and vehicle details for 46K+ vehicles nationwide.

- **URL**: https://apify.com/lulzasaur/kbb-scraper.md
- **Developed by:** [lulz bot](https://apify.com/lulzasaur) (community)
- **Categories:** E-commerce
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 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.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## KBB Scraper - Kelley Blue Book Cars for Sale

Scrape used and new car listings from [Kelley Blue Book](https://www.kbb.com/cars-for-sale/all/). Extract detailed vehicle data including VIN, pricing, KBB Fair Purchase Price, deal ratings, mileage, dealer info, and 30+ fields per listing.

### Features

- **46,000+ vehicles** nationwide from KBB's marketplace
- **KBB Fair Purchase Price** and deal rating (Great/Good/Fair/High)
- Filter by **make, model, year, price, mileage, location**
- Full vehicle specs: engine, transmission, drive type, fuel, MPG, colors
- Dealer info: name, phone, rating, reviews, city/state
- Listing metadata: days on site, hot deals, price reductions, newly listed flags

### Input Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `make` | string | - | Car make (e.g. toyota, honda, ford) |
| `model` | string | - | Car model (e.g. camry, civic). Requires make. |
| `zipCode` | string | 80202 | ZIP code for search location |
| `radius` | integer | 75 | Search radius in miles (10-500) |
| `yearFrom` | integer | - | Minimum model year |
| `yearTo` | integer | - | Maximum model year |
| `maxPrice` | number | - | Maximum listing price in USD |
| `maxMileage` | number | - | Maximum mileage in miles |
| `maxResults` | integer | 100 | Max listings to return (1-2000) |
| `proxyConfiguration` | object | none | Proxy settings |

### Output Fields

Each listing includes:

| Field | Description |
|-------|-------------|
| `id` | KBB listing ID |
| `title` | Full listing title |
| `vin` | Vehicle Identification Number |
| `year` | Model year |
| `make` | Manufacturer (Honda, Toyota, etc.) |
| `model` | Model name (Civic, Camry, etc.) |
| `trim` | Trim level (LX, EX, Sport, etc.) |
| `bodyStyle` | Body style (Sedan, SUV, Truck, etc.) |
| `listingType` | NEW or USED |
| `price` | Sale price in USD |
| `kbbFairPurchasePrice` | KBB Fair Purchase Price estimate |
| `kbbFairPriceLow` | KBB Fair Price range low |
| `kbbFairPriceHigh` | KBB Fair Price range high |
| `priceDelta` | Difference from KBB Fair Price |
| `dealRating` | KBB deal rating (Great/Good/Fair/High) |
| `mileage` | Odometer reading (formatted string) |
| `mileageNum` | Odometer reading (number) |
| `daysOnSite` | Days the listing has been active |
| `exteriorColor` | Exterior color |
| `interiorColor` | Interior color |
| `engine` | Engine type (4-Cylinder, V6, etc.) |
| `transmission` | Transmission type |
| `driveType` | Drive type (FWD, AWD, 4WD, RWD) |
| `fuelType` | Fuel type (Gasoline, Hybrid, Electric, etc.) |
| `mpgCity` | City fuel economy |
| `mpgHighway` | Highway fuel economy |
| `doors` | Number of doors |
| `isHot` | KBB "Hot" listing flag |
| `isNewlyListed` | Recently listed flag |
| `isReducedPrice` | Price recently reduced |
| `dealerName` | Dealer or seller name |
| `dealerPhone` | Dealer phone (if public) |
| `dealerRating` | Dealer rating (out of 5) |
| `dealerReviewCount` | Number of dealer reviews |
| `isPrivateSeller` | Whether seller is private (vs dealer) |
| `city` | Dealer city |
| `state` | Dealer state |
| `zip` | Dealer ZIP code |
| `distance` | Distance from search ZIP in miles |
| `imageUrl` | Primary listing image |
| `url` | Full KBB listing URL |

### Example Usage

#### Search all cars near Denver

```json
{
    "zipCode": "80202",
    "radius": 50,
    "maxResults": 100
}
```

#### Search for used Toyota Camry under $25K

```json
{
    "make": "toyota",
    "model": "camry",
    "maxPrice": 25000,
    "yearFrom": 2020,
    "maxResults": 200
}
```

#### Search for low-mileage SUVs

```json
{
    "maxMileage": 30000,
    "yearFrom": 2022,
    "maxResults": 500
}
```

### Use Cases

- **Car shopping** — Find the best deals using KBB Fair Purchase Price
- **Market analysis** — Track average prices by make/model/year
- **Dealer inventory monitoring** — Monitor dealer stock and pricing trends
- **Price comparison** — Compare asking prices vs KBB valuations
- **Automotive research** — Analyze vehicle market data at scale

### Technical Details

- Uses Cheerio (no browser needed) for fast, lightweight scraping
- Extracts data from KBB's Next.js server-side rendered `__NEXT_DATA__` JSON
- Handles 308/301 redirects automatically
- \~23 organic listings per page plus sponsored listings
- Respects rate limits with max concurrency of 2

# Actor input Schema

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

Filter by car make. Leave empty for all makes.

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

Filter by model (e.g. camry, civic, f-150). Requires make to be set.

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

Filter by vehicle condition.

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

ZIP code for search center. Defaults to 80202 (Denver, CO).

## `distance` (type: `string`):

Search radius from ZIP code.

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

Minimum listing price in USD.

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

Maximum listing price in USD.

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

Minimum model year (e.g. 2018).

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

Maximum model year (e.g. 2025).

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

Maximum mileage in miles.

## `maxResults` (type: `integer`):

Maximum number of listings to scrape. KBB returns ~23 per page.

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

Proxy settings for requests. KBB may work without proxies.

## Actor input object example

```json
{
  "make": "",
  "condition": "all",
  "zipCode": "80202",
  "distance": "nationwide",
  "maxResults": 200,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "zipCode": "80202",
    "maxResults": 200
};

// Run the Actor and wait for it to finish
const run = await client.actor("lulzasaur/kbb-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 = {
    "zipCode": "80202",
    "maxResults": 200,
}

# Run the Actor and wait for it to finish
run = client.actor("lulzasaur/kbb-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 '{
  "zipCode": "80202",
  "maxResults": 200
}' |
apify call lulzasaur/kbb-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,lulzasaur/kbb-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/VAwPW227MwR8bHU75/builds/DRYlgw8hKfXT7b3me/openapi.json