---
title: "Market Value"
description: "Estimate wholesale, retail, trade-in, and auction values for a vehicle by VIN, with optional mileage, state, and condition adjustments."
canonical_url: "https://docs.carsxe.com/docs/products/market-value"
markdown_url: "https://docs.carsxe.com/docs/products/market-value.md"
last_updated: "1980-01-01"
---

# Market Value
URL: /docs/products/market-value
LLM index: /llms.txt
Description: Estimate wholesale, retail, trade-in, and auction values for a vehicle by VIN, with optional mileage, state, and condition adjustments.

Estimate a vehicle's current market value from a VIN. Use `/v2/marketvalue` for new integrations: it returns vehicle identity plus wholesale and retail values across condition tiers. Add `mileage`, `state`, and `condition` when you want the estimate adjusted for a specific vehicle and market.

## When to use it

- Pricing inventory
- Estimating trade-in value
- Creating valuation workflows
- Comparing clean, average, rough, and extra-clean value ranges
- Adding valuation context after VIN decoding

## Parameters

| Parameter | Required | Description |
|---|---|---|
| `vin` | Yes | The 17-character vehicle identification number |
| `key` | Yes | Your CarsXE API key |
| `state` | No | US state used for regional adjustment. Example: `CA` |
| `mileage` | No | Current odometer mileage. Must be numeric |
| `condition` | No | One of `excellent`, `clean`, `average`, or `rough` |

If `condition` is omitted, use the returned condition buckets to choose the value range that matches your workflow.

## Example

<CodeGroup title="Get market value" tag="GET" label="/v2/marketvalue">

```bash
curl -G https://api.carsxe.com/v2/marketvalue \
  -d key=YOUR_API_KEY \
  -d vin=WBAFR7C57CC811956 \
  -d mileage=50000 \
  -d state=CA \
  -d condition=clean
```

```js
import { CarsXE } from "carsxe-api";

const carsxe = new CarsXE("YOUR_API_KEY");
const vin = "WBAFR7C57CC811956";
const mileage = "50000";
const state = "CA";
const condition = "clean";

try {
  const marketValue = await carsxe.marketvalue({ vin, mileage, state, condition });
  console.log(marketValue);
} catch (error) {
  console.error(error);
}
```

```python
import asyncio
from carsxe_api import CarsXE

carsxe = CarsXE("YOUR_API_KEY")
vin = "WBAFR7C57CC811956"
mileage = "50000"
state = "CA"
condition = "clean"

try:
    marketValue = asyncio.run(carsxe.market_value({"vin": vin, "mileage": mileage, "state": state, "condition": condition}))
    print(marketValue)
except Exception as e:
    print(f"Error: {e}")
```

```php
<?php
require_once __DIR__ . '/vendor/autoload.php';
use CarsxeDeveloper\Carsxe\Carsxe;

$carsxe = new Carsxe("YOUR_API_KEY");
$vin = "WBAFR7C57CC811956";
$mileage = "50000";
$state = "CA";
$condition = "clean";

try {
    $marketValue = $carsxe->marketValue(["vin" => $vin, "mileage" => $mileage, "state" => $state, "condition" => $condition]);
    print_r($marketValue);
} catch (Exception $error) {
    echo "Error: " . $error->getMessage();
}
```

```ruby
require "carsxe"

carsxe = Carsxe::CarsXE.new(api_key: "YOUR_API_KEY")
vin = "WBAFR7C57CC811956"
mileage = "50000"
state = "CA"
condition = "clean"

begin
  marketValue = carsxe.market_value("vin" => vin, "mileage" => mileage, "state" => state, "condition" => condition)
  puts marketValue
rescue StandardError => error
  puts "Error: #{error.message}"
end
```

```go
package main

import (
	"fmt"
	"github.com/carsxe/carsxe-go-package"
)

func main() {
	client := carsxe.New("YOUR_API_KEY")
	vin := "WBAFR7C57CC811956"
	mileage := "50000"
	state := "CA"
	condition := "clean"
	marketValue := client.MarketValue(map[string]string{"vin": vin, "mileage": mileage, "state": state, "condition": condition})
	fmt.Println(marketValue)
}
```

```java
import io.github.carsxe.CarsXE;
import java.util.Map;
import java.util.HashMap;

public class Main {
    public static void main(String[] args) {
        CarsXE carsxe = new CarsXE("YOUR_API_KEY");
        Map<String, String> params = new HashMap<>();
        params.put("vin", "WBAFR7C57CC811956");
        params.put("mileage", "50000");
        params.put("state", "CA");
        params.put("condition", "clean");

        try {
            Map<String, Object> marketValue = carsxe.marketvalue(params);
            System.out.println(marketValue);
        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}
```

```swift
import carsxe

let carsxe = CarsXE(apiKey: "YOUR_API_KEY")
let vin = "WBAFR7C57CC811956"
let mileage = "50000"
let state = "CA"
let condition = "clean"

do {
    let marketValue = try carsxe.marketValue(["vin": vin, "mileage": mileage, "state": state, "condition": condition])
    print(marketValue)
} catch {
    print("Error: \(error)")
}
```

```csharp
using carsxe;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        CarsXE carsxe = new CarsXE("YOUR_API_KEY");
        string vin = "WBAFR7C57CC811956";
        string mileage = "50000";
        string state = "CA";
        string condition = "clean";

        try
        {
            var marketValue = await carsxe.MarketValue(new Dictionary<string, string> { { "vin", vin }, { "mileage", mileage }, { "state", state }, { "condition", condition } });
            Console.WriteLine(marketValue);
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
        }
    }
}
```

```bash {{ title: "Response" }}
{
  "uid": "FDE60872",
  "input": {
    "vin": "WBAFR7C57CC811956",
    "country": "US"
  },
  "publish_date": "4/8/2025",
  "state": "NT",
  "country": "US",
  "model_year": "2012",
  "make": "BMW",
  "model": "5-Series",
  "series": "535i",
  "style": "4D Sedan",
  "class_name": "Luxury Car",
  "whole_clean": {
    "base_whole_clean": 5300,
    "mileage_whole_clean": 0,
    "add_deduct_whole_clean": 0,
    "regional_whole_clean": 0
  },
  "retail_clean": {
    "base_retail_clean": 9325,
    "mileage_retail_clean": 0,
    "add_deduct_retail_clean": 0,
    "regional_retail_clean": 0
  }
}
```

</CodeGroup>

## Response

### Top-level shape

<MarketValueTopLevelShape />

Click any value bucket to expand it and see sample data. For the full interactive reference, try it live in the [API Reference](/api-reference).

All response fields are optional. Missing value buckets mean the provider did not return that valuation for the VIN or market context.

<Properties>
  <Property name="uid" type="string">
    Valuation record identifier.
  </Property>
  <Property name="input" type="object">
    Echo of request inputs and inferred country.
  </Property>
  <Property name="publish_date" type="string">
    Provider valuation publish date.
  </Property>
  <Property name="state" type="string">
    Market region used for the valuation.
  </Property>
  <Property name="country" type="string">
    Country used for the valuation.
  </Property>
  <Property name="model_year" type="string">
    Vehicle model year.
  </Property>
  <Property name="make" type="string">
    Manufacturer.
  </Property>
  <Property name="model" type="string">
    Model name.
  </Property>
  <Property name="series" type="string">
    Trim or series.
  </Property>
  <Property name="style" type="string">
    Body style.
  </Property>
  <Property name="class_name" type="string">
    Vehicle class.
  </Property>
  <Property name="whole_*" type="object">
    Wholesale values for a condition tier.
  </Property>
  <Property name="retail_*" type="object">
    Retail values for a condition tier.
  </Property>
</Properties>

## How to read value buckets

<details>
<summary>**Condition tiers** - excellent, clean, average, and rough values</summary>

| Suffix | Meaning |
|---|---|
| `xclean` | Excellent / extra-clean condition |
| `clean` | Clean condition |
| `avg` | Average condition |
| `rough` | Rough condition |

The request parameter `condition=excellent` maps conceptually to the `xclean` tier in the response.

</details>

<details>
<summary>**Value families** - wholesale and retail buckets</summary>

| Prefix | Meaning |
|---|---|
| `whole_*` | Wholesale-oriented valuation bucket |
| `retail_*` | Retail-oriented valuation bucket |

</details>

<details>
<summary>**Adjustment fields** - base value plus mileage, add/deduct, and regional adjustments</summary>

The `*` is replaced by the value family and condition tier. For example, `base_retail_clean` is the base retail value for a clean vehicle.

<Properties>
  <Property name="base_*" type="number">
    Base valuation before mileage, equipment, or regional adjustments.
  </Property>
  <Property name="mileage_*" type="number">
    Mileage adjustment applied to the valuation.
  </Property>
  <Property name="add_deduct_*" type="number">
    Additions or deductions applied by the provider.
  </Property>
  <Property name="regional_*" type="number">
    Regional market adjustment.
  </Property>
</Properties>

</details>

## Errors

| Status | When it happens |
|---|---|
| `400` | Missing VIN, wrong VIN length, invalid mileage, or invalid condition |
| `401` | Missing or invalid API key |
| `404` | No market value data found for this VIN |
| `429` | Usage limit exceeded |
| `500` | Internal server error |
| `503` | Upstream market value provider unavailable |

Valid condition values:

```text
excellent, clean, average, rough
```

See the [Errors guide](/docs/guides/errors) for general error handling guidance.

## Legacy v1 endpoint

Use `/v2/marketvalue` for new integrations. Legacy `/marketvalue` still exists for older integrations and returns simpler fields such as `retail`, `tradeIn`, `roughTradeIn`, `averageTradeIn`, `loanValue`, `msrp`, `tradeInValues`, and `auctionValues`.

```bash
curl -G https://api.carsxe.com/marketvalue \
  -d key=YOUR_API_KEY \
  -d vin=WBAFR7C57CC811956
```

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).