# Car Value, Depreciation & 5-Year Cost to Own (`prodiger/car-valuation-scraper`) Actor

Get used-car market value, model depreciation curves, and 5-year cost-to-own (fuel + CO₂) for any make/model/year via the official vehicles.dev API. Batch a list of vehicles, no scraping, no CAPTCHAs. Pay-per-result.

- **URL**: https://apify.com/prodiger/car-valuation-scraper.md
- **Developed by:** [Arnas](https://apify.com/prodiger) (community)
- **Categories:** E-commerce, Lead generation
- **Stats:** 3 total users, 1 monthly users, 99.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

Get **used-car market value, depreciation curves, and 5-year cost-to-own** for any make, model, and year — in bulk, from one clean API. Feed the actor a list of vehicles and it returns a structured valuation row for each: estimated market value in USD, a model depreciation curve (retention by age), and annual + 5-year fuel cost with MPG and CO₂.

Powered by the official **[vehicles.dev](https://vehicles.dev)** API — **no scraping, no proxies, no CAPTCHAs, and nothing that breaks when a website changes its HTML.**

### What does Car Value, Depreciation & Cost to Own do?

This actor is a batch front-end to three [vehicles.dev](https://vehicles.dev) endpoints:

- **Market value** — an estimated used-car asking price (USD) for a specific year/make/model, optionally refined by mileage, trim, state, condition, drivetrain and more. Each estimate reports the model's median error (`medianApePct`) so you know how tight it is.
- **Depreciation** — a model-level depreciation curve: annual decay rate, retention by age (0–12 years), and per-model-year detail. Great for residual-value and resale forecasting.
- **Cost to own** — annual and 5-year fuel cost, combined MPG, fuel type, and CO₂ grams per mile, sourced from EPA data.

Give it one vehicle or ten thousand. Results download as **JSON, CSV, Excel, or HTML**, or stream live via the [Apify API](https://docs.apify.com/api/v2). Run it on demand or [schedule it](https://docs.apify.com/platform/schedules) to refresh valuations over time. Because it runs on Apify you get API access, scheduling, monitoring, and integrations (Zapier, Make, Google Sheets, webhooks) for free.

### Why use this actor?

- **No API key required** — the actor ships preconfigured. Paste vehicles, hit start.
- **Official data source, not a scraper** — [vehicles.dev](https://vehicles.dev) is a licensed vehicle-data API, so results are clean JSON that don't break when a marketplace redesigns its site.
- **Batch + dedup** — price a whole list in one run. Identical vehicles (same make/model/year) are deduplicated so you never pay twice for the same lookup.
- **Pay only for what returns** — you're billed per result actually written to the dataset. Nulls and failures cost nothing.
- **Pick your datasets** — turn market value, depreciation, and cost-to-own on or off independently to control cost.

Common use cases: **used-car pricing tools**, **dealer inventory valuation**, **fleet residual-value modeling**, **lease/finance cost-to-own calculators**, **automotive marketplaces**, **insurance and total-loss valuation**, and **academic / market research**.

### How to use Car Value, Depreciation & Cost to Own

1. Click **Try for free** (or open the actor in your Apify Console).
2. In **Vehicles**, paste a list of vehicles as JSON — for example:
   ```json
   [
     { "make": "Toyota", "model": "Camry", "year": 2021, "miles": 45000, "state": "TX" },
     { "make": "Ford", "model": "F-150", "year": 2022 }
   ]
   ```
   (Or just fill in the single **Make / Model / Year** fields to price one vehicle.)
3. Under **Datasets**, choose which of *market value*, *depreciation*, and *cost to own* you want.
4. Click **Start**. Rows populate as each vehicle is priced.
5. Download the dataset as **JSON / CSV / Excel**, or fetch it via the [Apify API](https://docs.apify.com/api/v2).

### Input

| Field | Type | Description |
|-------|------|-------------|
| `vehicles` | array | List of `{ make, model, year }` objects. `year` is required for market value and cost-to-own; depreciation works without it. Each object may include per-vehicle refiners (`miles`, `trim`, `state`, …) that override the run-level ones. |
| `make` / `model` / `year` | string / string / int | Single-vehicle shortcut, used only when `vehicles` is empty. |
| `marketValue` | boolean | Fetch the market-value estimate. Default `true`. |
| `depreciation` | boolean | Fetch the depreciation curve. Default `true`. |
| `ownershipCosts` | boolean | Fetch 5-year cost-to-own. Default `false`. |
| `miles`, `trim`, `state`, `condition`, `drivetrain`, `fuel`, `transmission`, `bodyStyle`, `color`, `baseMsrp` | mixed | Optional run-level market-value refiners. |
| `maxConcurrency` | int | Vehicles priced in parallel (default 5). |
| `apiKey` | string (secret) | Optional. Bring your own vehicles.dev key to use your own quota. |
| `customMapFunction` | string | Optional JS to reshape each row before it is saved. |

### Output

Each dataset row merges the requested datasets for one vehicle, with headline numbers flattened for the table view and full upstream payloads kept nested:

```json
{
  "make": "Toyota",
  "model": "Camry",
  "year": 2021,
  "coverage": ["marketValue", "depreciation", "ownershipCosts"],
  "estimateUsd": 26096,
  "currency": "USD",
  "medianApePct": 3.7,
  "annualDecay": 0.0652,
  "combinedMpg": 26,
  "annualFuelCostUsd": 2350,
  "fiveYearFuelCostUsd": 11750,
  "co2GramsPerMile": 338,
  "fuelType": "Regular",
  "marketValue": { "estimateUsd": 26096, "currency": "USD", "medianApePct": 3.7, "inputs": { "…": "…" } },
  "depreciation": { "annualDecay": 0.0652, "byModelYear": [], "curveByAge": [] },
  "ownershipCosts": { "combinedMpg": 26, "annualFuelCostUsd": 2350, "…": "…" },
  "requestedAt": "2026-08-15T10:49:38.000Z",
  "source": "vehicles.dev"
}
```

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. The `coverage` array tells you exactly which datasets were returned for each vehicle; a field is `null` when its dataset was not requested or was unavailable for that vehicle.

#### Data fields

| Field | Meaning |
|-------|---------|
| `estimateUsd` | Estimated market value in whole USD. |
| `medianApePct` | The valuation model's median absolute % error (lower = tighter). |
| `annualDecay` | Fitted annual depreciation rate for the model. |
| `combinedMpg` | EPA combined MPG. |
| `annualFuelCostUsd` / `fiveYearFuelCostUsd` | Estimated fuel cost (fuel only). |
| `co2GramsPerMile` | Tailpipe CO₂ grams per mile. |
| `coverage` | Which datasets were returned for the row. |
| `errors` / `notes` | Per-dataset failures / skips (e.g. "requires year"), when any. |

### How much does it cost?

Billing is **pay-per-result**: a small per-run start fee plus a charge for each dataset result actually returned. You choose which datasets to fetch, so you control the cost. Turning off a dataset you don't need means you're never billed for it. Deduplication by make/model/year means overlapping inputs never double-bill. Failed or empty lookups are free.

### Tips & advanced options

- **Sharper valuations:** add `miles` and `state` (and `trim`) — omitting mileage widens the estimate.
- **Cheaper runs:** leave `ownershipCosts` off unless you need fuel/CO₂; keep `marketValue` + `depreciation` for the core picture.
- **Depreciation without a year:** depreciation is model-level, so entries with no `year` still return a curve.
- **Concurrency:** the vehicles.dev rate limit is per-account, so the default `maxConcurrency` of 5 suits the free tier; raise it if you bring a higher-tier key.

### FAQ, disclaimers & support

**Is this real-time market data?** Estimates are modeled from observed listing data via [vehicles.dev](https://vehicles.dev); they're guidance, not a guaranteed sale price. Each market-value row includes `medianApePct` so you can gauge confidence.

**Does depreciation vary by trim or VIN?** No — depreciation is computed at the make/model level, so the curve is the same across trims and model-years of that model.

**What does cost-to-own include?** Fuel and CO₂ only (from EPA data). It excludes insurance, maintenance, and depreciation, and assumes ~15,000 miles/year.

**Do I need a vehicles.dev account?** No. The actor is preconfigured. Advanced users can supply their own `apiKey` to run against their own quota.

**Something look off?** Use the **Issues** tab to report it. Custom fields or a tailored vehicle-data pipeline can be built on request.

*Data is provided by the official [vehicles.dev](https://vehicles.dev) API.*

# Actor input Schema

## `vehicles` (type: `array`):

The vehicles to price. Each entry is an object with `make`, `model`, and (recommended) `year`. `year` is required for market value and cost-to-own; depreciation is model-level and works without it. You can also add per-vehicle market-value refiners (`miles`, `trim`, `state`, …) that override the run-level ones. Example: `[{ "make": "Toyota", "model": "Camry", "year": 2021, "miles": 45000, "state": "TX" }]`.

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

Convenience shortcut for pricing one vehicle. Only used when the `vehicles` list above is empty. Title-case, e.g. `Toyota`.

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

Model for the single-vehicle shortcut. Title-case, e.g. `Camry`. Only used when `vehicles` is empty.

## `year` (type: `integer`):

Model year for the single-vehicle shortcut. Only used when `vehicles` is empty.

## `marketValue` (type: `boolean`):

Fetch the estimated used-car market value (USD) for each vehicle. Requires a year.

## `depreciation` (type: `boolean`):

Fetch the model's depreciation curve (retention by age, annual decay). Model-level — no year required.

## `ownershipCosts` (type: `boolean`):

Fetch annual + 5-year fuel cost, combined MPG, and CO₂ per mile. Requires a year. Off by default.

## `miles` (type: `integer`):

Run-level odometer reading applied to every market-value lookup (a per-vehicle `miles` overrides it). Improves valuation accuracy.

## `trim` (type: `string`):

Trim level, e.g. `SE`, `Limited`.

## `state` (type: `string`):

2-letter US state code, e.g. `TX`. Regional price adjustment.

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

e.g. `used`, `new`, `cpo`. Defaults to used.

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

e.g. `FWD`, `AWD`, `4WD`.

## `fuel` (type: `string`):

e.g. `Gasoline`, `Hybrid`, `Electric`.

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

e.g. `Automatic`, `Manual`.

## `bodyStyle` (type: `string`):

e.g. `Sedan`, `SUV`, `Truck`.

## `color` (type: `string`):

Exterior color.

## `baseMsrp` (type: `integer`):

Original base MSRP in whole USD, if known.

## `maxConcurrency` (type: `integer`):

How many vehicles to price in parallel. The vehicles.dev rate limit is per-account, so keep this at 5 on the free tier (higher on Pro/Scale).

## `maxRequestRetries` (type: `integer`):

Retry budget per API request for rate limits (429) and transient 5xx errors.

## `apiKey` (type: `string`):

Optional. The actor is preconfigured, so you can leave this blank. Supply your own vehicles.dev key (prefixed `vdev_`) to run against your own quota. Get one free at https://vehicles.dev.

## `customMapFunction` (type: `string`):

Optional JavaScript function body that transforms each row before it is saved. Receives the item as `item` and must return the modified item. Example: `return { make: item.make, model: item.model, value: item.estimateUsd };`

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

Optional. vehicles.dev is an official API (no anti-bot) and its rate limit is per-account, not per-IP, so a proxy does not raise throughput. Off by default.

## Actor input object example

```json
{
  "vehicles": [
    {
      "make": "Toyota",
      "model": "Camry",
      "year": 2021,
      "miles": 45000,
      "state": "TX"
    },
    {
      "make": "Ford",
      "model": "F-150",
      "year": 2022
    }
  ],
  "marketValue": true,
  "depreciation": true,
  "ownershipCosts": false,
  "maxConcurrency": 5,
  "maxRequestRetries": 4,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

One row per vehicle — market value, depreciation, and cost-to-own.

# 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 = {
    "vehicles": [
        {
            "make": "Toyota",
            "model": "Camry",
            "year": 2021,
            "miles": 45000,
            "state": "TX"
        },
        {
            "make": "Ford",
            "model": "F-150",
            "year": 2022
        }
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("prodiger/car-valuation-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 = { "vehicles": [
        {
            "make": "Toyota",
            "model": "Camry",
            "year": 2021,
            "miles": 45000,
            "state": "TX",
        },
        {
            "make": "Ford",
            "model": "F-150",
            "year": 2022,
        },
    ] }

# Run the Actor and wait for it to finish
run = client.actor("prodiger/car-valuation-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 '{
  "vehicles": [
    {
      "make": "Toyota",
      "model": "Camry",
      "year": 2021,
      "miles": 45000,
      "state": "TX"
    },
    {
      "make": "Ford",
      "model": "F-150",
      "year": 2022
    }
  ]
}' |
apify call prodiger/car-valuation-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,prodiger/car-valuation-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/UqZc7iaUeYXhfdW8U/builds/KNAknJ0H656tBN2zo/openapi.json