The **Vehicle Market Value API** provides access to a library of vehicle market value data.
The Vehicle Market Value API **estimates** the market value for **used** and **new** cars by **VIN** based on **millions** of historical vehicle sales stored in CarsXE's sales database.
With the assumption that sale prices are normally distributed, CarsXE's market value model estimates the "below market" and "above market" values within a distribution.
---
This endpoint allows you to retrieve the **market value** for a specific vehicle based on its **VIN**.
## Required attributes
Your CarsXE **API key**.
The 17 character long vehicle identification number.
## Optional attributes
The **US state** of the vehicle to get the **market value** for.
The **current odometer** reading (miles in the US, kilometers in Canada). Must be a **valid numeric value**. When you pass `mileage` with `condition`, the API selects the matching `mileage_list` band and writes that band into the `mileage_*` fields, then recalculates `adjusted_*`. If you omit `mileage`, use `mileage_list` to apply bands yourself.
The **overall condition** of the vehicle. Accepted values are:
excellent, clean, average, or rough.
`excellent` maps to the `xclean` response tier. Used with `mileage` to apply the matching mileage band.
Each condition object (`whole_*`, `retail_*`, `trade_in_*`) exposes `base_*`, `mileage_*`, `add_deduct_*`, `regional_*`, and `adjusted_*`. The final value is:
`adjusted_*` = `base_*` + `mileage_*` + `add_deduct_*` + `regional_*`
**Mileage.** `mileage_list` is the full table of odometer bands, including `finadv` and `mileage_cat` when the provider supplies them. Passing `mileage` applies the matching band automatically; otherwise clients can apply a band themselves.
**Options.** `add_deduct_list` is the table of option/equipment adds and deducts. Those rows adjust market value based on options the vehicle may have. The `add_deduct_*` fields on each condition object hold the option adjustment already applied to that bucket.
---
## Response attributes
A **unique identifier** for for the vehicle.
A map of the input: "**vin**", "**state**", "**country**" of the vehicle.
The **date** when the vehicle **market value** data was last published or **updated**.
The **frequency of data updates**.
It indicates that the market value data provided by the API is updated **once per day.**
The state where the vehicle's market value is being assessed, in this case, **California**.
The country context for the valuation, in this case, the **United States**.
The **unique vehicle code**.
It is a unique identifier assigned to a specific vehicle configuration or model. This code helps in accurately identifying and retrieving precise market value data for that particular vehicle.
A **group identifier** used to classify or associate the vehicle with a specific category, market segment, or data grouping.
e.g., sedans, SUVs.
The **manufacturing year** of the vehicle model being assessed. This information is crucial as it directly impacts the vehicle's market value, reflecting depreciation, demand, and historical relevance in pricing calculations.
The **brand** or **manufacturer** of the vehicle, in this case, **Lexus**.
The **model** of the vehicle, which is a particular version of the Lexus brand, here being the **RX 350**.
The series associated with the vehicle.
Describes the vehicle **style** or **body type**. In this case:
* **4D** refers to a four-door vehicle.
* **SUV** indicates the vehicle type is a Sport Utility Vehicle.
* **AWD** stands for All-Wheel Drive, indicating the type of drivetrain.
A **category** for the vehicle's **mileage**, could represent a specific mileage **range** or **classification**.
A **class code** that categorizes the vehicle into a specific **segment** or **type**.
This is a human-readable description of the **vehicle's class**. It specifies that the vehicle is categorized as a **large luxury crossover/SUV**, helping to describe the vehicle's type or market segment.
A **rating** or **score** based on the vehicle's description quality or completeness.
Indicates whether the vehicle's market value data is the **first set of values** being used or provided. In this case, it's set to **false**, meaning the data may not be the initial set or it has been updated or revisited.
A **risk score** associated with the vehicle's market value or condition. A risk score might assess factors such as potential for accidents, fraud, or reliability concerns.
**Excellent** condition, typically with no significant wear.
**Good** condition, with minor wear.
**Average** condition, showing moderate wear.
**Poor** condition, showing significant wear or issues.
For each category (e.g., "whole_xclean"), there are further subfields:
* **base_whole_xclean**: The base value of the vehicle in **excellent** condition, **before adjustments** (e.g., mileage or regional factors).
* **mileage_whole_xclean**: Adjustments for mileage (if any).
* **add_deduct_whole_xclean**: Any other **additions** or **deductions** (for special features or damages).
* **regional_whole_xclean**: Adjustments based on regional market differences.
* **adjusted_whole_xclean**: The final, **adjusted market value** for the vehicle.
The **retail price** of a vehicle in **excellent** condition (no significant wear, like new or almost new).
The **retail price** for a vehicle in **good** condition (minor wear and tear, but well-maintained).
The **retail price** of a vehicle in **average** condition (moderate wear, typically for a used vehicle).
The **retail price** for a vehicle in **poor** condition (significant wear and tear, possible mechanical or cosmetic issues).
The **trade-in price** for a vehicle in **good** condition (minor wear and tear, well-maintained, ready for resale or continued use).
The **trade-in price** for a vehicle in **average** condition (moderate wear, typical for a used vehicle with normal signs of use).
The **trade-in price** for a vehicle in **poor** condition (significant wear, potential mechanical or cosmetic issues, or higher depreciation).
Raw regional adjustment amount for **region 2**. Passing `state` selects which regional amount is copied onto each condition object's `regional_*` field.
Raw regional adjustment amount for **region 3**.
Raw regional adjustment amount for **region 4**.
Raw regional adjustment amount for **region 5**.
Raw regional adjustment amount for **region 6**.
Manufacturer’s Suggested Retail Price (MSRP) is the **recommended selling price** set by the vehicle manufacturer for the vehicle before any dealer discounts or additions. It is often used as a starting point for pricing.
The **retail price** of the vehicle **equipped** with all available options and features, including any add-ons, upgrades, or packages.
This describes the **options** or **features** that are **included** in the vehicle’s price. It lists the additional equipment or features that are part of the specified price.
* **AC**: Air Conditioning
* **AT**: Automatic Transmission
* **LTH**: Leather Upholstery
* **SR**: Sunroof
The wheelbase is the **distance** (106.9 inches) between the front and rear axles of the vehicle. It can affect the vehicle's handling, ride quality, and interior space.
The tire size indicates the **dimensions** of the tires installed on the vehicle. This includes:
* **225**: The tire width in millimeters.
* **65**: The aspect ratio (the height of the tire sidewall as a percentage of the width).
* **SR**: The speed rating (indicating the maximum speed the tire is rated for).
* **17**: The diameter of the tire in inches.
**Gross Vehicle Weight** (GVW) is the total weight (5,245 pounds) of the vehicle, **including its maximum load** (passengers, cargo, etc.).
The **seating capacity** indicates the **number of passengers** the vehicle can accommodate.
The **type** of **fuel** the vehicle uses.
The **fuel capacity** refers to the volume of fuel the vehicle's tank can hold, usually in gallons.
Fuel **delivery system** type used by the vehicle. MPI stands for **Multi-Point Fuel Injection**, which is a type of fuel injection system where each cylinder has its own injector, allowing more precise control of fuel delivery.
**Highway Miles Per Gallon** (MPG) represents the vehicle's fuel efficiency on highways or at constant speeds.
**City Miles Per Gallon** (MPG) indicates the vehicle’s fuel efficiency in urban or stop-and-go driving conditions.
This field provides a description of the vehicle’s engine.
* **3.5L**: The **engine’s displacement**, meaning it has a 3.5-liter engine capacity.
* **V6**: The engine has six **cylinders** arranged in a V-shape.
* **SFI**: **Sequential Fuel Injection**, a system where fuel is injected into each cylinder at the appropriate time.
* **DOHC**: Double Overhead Camshaft, indicating the engine has two camshafts controlling the intake and exhaust valves for better performance.
The number of **cylinders** in the engine.
The **engine displacement** refers to the total volume of all the cylinders in the engine, often measured in liters.
The base horsepower of the engine, which measures its maximum power output.
* **270**: The engine produces 270 horsepower at the specified RPM.
* **6200**: The engine reaches 270 horsepower at 6,200 RPM (revolutions per minute).
The **taxable horsepower** refers to the engine’s power rating used for tax or registration purposes, which might be calculated differently from the base horsepower.
The engine’s **torque** is a measure of its **rotational force**, important for acceleration and towing capacity.
* **251**: The engine generates 251 lb-ft of torque.
* **4700**: This torque is available at 4,700 **RPM**.
The type of transmission the vehicle uses. The vehicle has an **automatic** transmission, as indicated by "**A**".
The vehicle’s **drivetrain** indicates how power is delivered to the wheels. The vehicle has **All-Wheel Drive** (AWD), meaning power is distributed to all four wheels for better traction, especially in poor road conditions.
The **number of gears** in the vehicle's transmission.
The number of **exterior doors** the vehicle has. The vehicle has **4 doors**, which is typical for a sedan or a 4-door SUV.
Airbag configuration returned for the vehicle. Example: `"Side Curtain"` or `"Side Curtain; Supplemental Restraint System"`.
Corrosion / rust warranty. Example: `"5-year/100,000-mile, Limited"`.
The basic warranty for the vehicle, covering **repairs** or **defects** within a **specified time** or **mileage** limit.
* **4-year/50,000-mile**: The warranty lasts for 4 years or 50,000 miles, whichever comes first.
* **Limited**: The warranty is limited, meaning it may not cover all components or may have exclusions.
Roadside-assistance warranty. Example: `"5-year/60,000-mile"` or `"4-year/Unlimited-mile"`.
Option and equipment **adds and deducts**. These rows adjust market value based on options the vehicle may have or lack. The `add_deduct_*` fields on each condition object hold the option adjustment already applied to that bucket.
* **uoc**: Unique option code (UOC).
* **name**: Option or equipment name. Example: `"w/o Auto Trans"`.
* **xclean**, **clean**, **avg**, **rough**:
Dollar adjustment for that option at each condition tier (positive = add, negative = deduct).
* **auto**: Whether the option is treated as automatic / default (`Y` or `N`).
* **resid12**, **resid24**, **resid30**, **resid36**, **resid42**, **resid48**, **resid60**, **resid72**:
Residual amounts for the option at those lease months.
This is a list of model numbers associated with the vehicle.
Table of **mileage / kilometer bands** with value adjustments per condition. Live responses include many rows covering `1` through `999999`. If you pass the `mileage` query parameter with `condition`, the API selects the matching band and applies it to the `mileage_*` fields automatically. Otherwise you can apply a band yourself.
* **model_year**: Model year this band applies to.
* **range_begin**: Inclusive start of the odometer band.
* **range_end**: Inclusive end of the odometer band.
* **xclean**, **clean**, **avg**, **rough**:
Adjustment amounts for extra-clean / excellent, clean, average, and rough condition.
* **finadv**: Finance-advance adjustment for this band, when the provider supplies one.
* **mileage_cat**: Mileage category for the band. Matches top-level `mileage_cat`.
The **retail value** of the vehicle, which represents the **expected** price if the vehicle is sold to a **consumer**, typically by a **dealership**.
The **trade-in value** of the vehicle, which is how much a dealership would offer to accept the vehicle as a trade-in for purchasing a different vehicle.
The **rough trade-in value** of the vehicle, which represents the lowest price a dealership would offer for a vehicle in **poor condition** (rough).
The **average trade-in value**, which represents a middle ground or average trade-in price for a vehicle in **average condition**.
The **loan value** of the vehicle, which is the estimated amount the vehicle would be financed for, typically used by **banks** or **financial institutions** for vehicle loans.
This field would typically contain additional details related to trade-in values **over time** or **across different conditions**.
The **auction values** represent the price range that the vehicle could sell for at an auction, which is typically lower than retail but higher than trade-in values. Auction prices depend on the vehicle's condition and demand.
* **low_auction_value**: The lowest expected price the vehicle could sell for at an auction, in this case, $3,150.
* **average_auction_value**: The average price the vehicle is expected to sell for at an auction, in this case, $4,400.
* **high_auction_value**: The highest expected price the vehicle could sell for at an auction, in this case, $5,675.
* **date_range**: The date range during which the auction values are applicable. In this case, the values are for 12/18/2024.
You may be use the following VINs for test:JN1EV7AP6JM355294WBAFR7C57CC811956
},{question: "Is the Vehicle Market Value API included in the free Sandbox?", answer: <>Yes! The Vehicle Market Value API is included in the free Sandbox with a lifetime limit of 5 API calls. For more information visit our pricing page.}]} hidePadding />
```bash
curl -G https://api.carsxe.com/v2/marketvalue \
-d key=CARSXE_API_KEY \
-d vin=WBAFR7C57CC811956
```
```js
import { CarsXE } from "carsxe-api";
const carsxe = new CarsXE("CARSXE_API_KEY");
const vin = "WBAFR7C57CC811956";
try {
const marketValue = await carsxe.marketvalue({ vin });
console.log(marketValue);
} catch (error) {
console.error(error);
}
```
```python
import asyncio
from carsxe_api import CarsXE
carsxe = CarsXE('CARSXE_API_KEY')
vin = 'WBAFR7C57CC811956'
try:
marketValue = asyncio.run(carsxe.market_value({"vin": vin}))
print(marketValue)
except Exception as e:
print(f"Error: {e}")
```
```php
marketValue(['vin' => $vin]);
print_r($marketValue);
} catch (Exception $error) {
echo "Error: " . $error->getMessage();
}
```
```ruby
require 'carsxe'
API_KEY = 'CARSXE_API_KEY'
carsxe = Carsxe::CarsXE.new(api_key: API_KEY)
vin = 'WBAFR7C57CC811956'
begin
marketValue = carsxe.market_value('vin' => vin)
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("CARSXE_API_KEY")
vin := "WBAFR7C57CC811956"
marketValue := client.MarketValue(map[string]string{"vin": vin})
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("CARSXE_API_KEY");
Map params = new HashMap<>();
params.put("vin", "WBAFR7C57CC811956");
try {
Map marketValue = carsxe.marketvalue(params);
System.out.println(marketValue);
} catch (Exception e) {
System.err.println("Error: " + e.getMessage());
}
}
}
```
```swift
import carsxe
let carsxe = CarsXE(apiKey: "CARSXE_API_KEY")
let vin = "WBAFR7C57CC811956"
do {
let marketValue = try carsxe.marketValue(["vin": vin])
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)
{
string API_KEY = "CARSXE_API_KEY";
CarsXE carsxe = new CarsXE(API_KEY);
string vin = "WBAFR7C57CC811956";
try
{
var marketValue = await carsxe.MarketValue(new Dictionary { { "vin", vin } });
Console.WriteLine(marketValue);
}
catch (Exception ex)
{
Console.WriteLine($"Error: {ex.Message}");
}
}
}
```
```json showLineNumbers {{ title: 'Response' }}
{
"uid": "6AA32D4C",
"input": {
"vin": "3KPFK4A78HE103497",
"state": "CA",
"country": "US"
},
"publish_date": "8/29/2025",
"data_freq": "D",
"state": "CA",
"country": "US",
"uvc": "2017485075",
"group_num": "4163",
"model_year": "2017",
"make": "Kia",
"model": "Forte",
"series": "LX",
"style": "4D Sedan",
"mileage_cat": "B",
"class_code": "A",
"class_name": "Small Car",
"description_score": "",
"first_values_flag": false,
"risk_score": "",
"whole_xclean": {
"base_whole_xclean": 5925,
"mileage_whole_xclean": 0,
"add_deduct_whole_xclean": 0,
"regional_whole_xclean": 25,
"adjusted_whole_xclean": 5950
},
"whole_clean": {
"base_whole_clean": 4950,
"mileage_whole_clean": 0,
"add_deduct_whole_clean": 0,
"regional_whole_clean": 25,
"adjusted_whole_clean": 4975
},
"whole_avg": {
"base_whole_avg": 3600,
"mileage_whole_avg": 0,
"add_deduct_whole_avg": 0,
"regional_whole_avg": 25,
"adjusted_whole_avg": 3625
},
"whole_rough": {
"base_whole_rough": 2300,
"mileage_whole_rough": 0,
"add_deduct_whole_rough": 0,
"regional_whole_rough": 25,
"adjusted_whole_rough": 2325
},
"retail_xclean": {
"base_retail_xclean": 9750,
"mileage_retail_xclean": 0,
"add_deduct_retail_xclean": 0,
"regional_retail_xclean": 25,
"adjusted_retail_xclean": 9775
},
"retail_clean": {
"base_retail_clean": 8575,
"mileage_retail_clean": 0,
"add_deduct_retail_clean": 0,
"regional_retail_clean": 25,
"adjusted_retail_clean": 8600
},
"retail_avg": {
"base_retail_avg": 6550,
"mileage_retail_avg": 0,
"add_deduct_retail_avg": 0,
"regional_retail_avg": 25,
"adjusted_retail_avg": 6575
},
"retail_rough": {
"base_retail_rough": 5050,
"mileage_retail_rough": 0,
"add_deduct_retail_rough": 0,
"regional_retail_rough": 25,
"adjusted_retail_rough": 5075
},
"trade_in_clean": {
"base_trade_in_clean": 5055,
"mileage_trade_in_clean": 0,
"add_deduct_trade_in_clean": 0,
"regional_trade_in_clean": 25,
"adjusted_trade_in_clean": 5080
},
"trade_in_avg": {
"base_trade_in_avg": 3705,
"mileage_trade_in_avg": 0,
"add_deduct_trade_in_avg": 0,
"regional_trade_in_avg": 25,
"adjusted_trade_in_avg": 3730
},
"trade_in_rough": {
"base_trade_in_rough": 2205,
"mileage_trade_in_rough": 0,
"add_deduct_trade_in_rough": 0,
"regional_trade_in_rough": 25,
"adjusted_trade_in_rough": 2230
},
"region2": 50,
"region3": 25,
"region4": -25,
"region5": 0,
"region6": 0,
"msrp": 17600,
"retail_equipped": 18820,
"price_includes": "AC",
"wheel_base": 106.3,
"tire_size": "195/65R15",
"seat_cap": "5",
"fuel_type": "Gas",
"fuel_cap": "13.2",
"fuel_delivery": "MPI",
"hwy_mpg": "38",
"city_mpg": "29",
"engine_description": "2.0L I-4 MPI DOHC ",
"cylinders": "4",
"engine_displacement": "2.0L",
"base_hp": "147 @ 6200",
"taxable_hp": 16.7,
"torque": "132 @ 4500",
"drivetrain": "FWD",
"num_gears": "6",
"ext_doors": "4",
"airbags": "Side Curtain",
"anti_corrosion_warranty": "5-year/100,000-mile, Limited",
"basic_warranty": "5-year/60,000-mile, Limited",
"road_assist_warranty": "5-year/60,000-mile",
"add_deduct_list": [
{
"uoc": "05",
"name": "w/o Auto Trans",
"xclean": -550,
"clean": -550,
"avg": -550,
"rough": -550,
"auto": "N",
"resid12": 0,
"resid24": 0,
"resid30": 0,
"resid36": 0,
"resid42": 0,
"resid48": 0,
"resid60": 0,
"resid72": 0
}
],
"model_number_list": ["C3421", "C3422"],
"mileage_list": [
{
"model_year": "2017",
"range_begin": 1,
"range_end": 8000,
"xclean": 2800,
"clean": 3000,
"avg": 3200,
"rough": 3200,
"finadv": 2900,
"mileage_cat": "B"
},
{
"model_year": "2017",
"range_begin": 110001,
"range_end": 113000,
"xclean": -250,
"clean": -125,
"avg": 0,
"rough": 125,
"finadv": -175,
"mileage_cat": "B"
},
{
"model_year": "2017",
"range_begin": 214001,
"range_end": 999999,
"xclean": -3325,
"clean": -3325,
"avg": -3325,
"rough": -3225,
"finadv": -3325,
"mileage_cat": "B"
}
],
"retail": 6550,
"trade_in": 5055,
"rough_trade_in": 2205,
"average_trade_in": 3705,
"loan_value": 8575,
"trade_in_values": [],
"auction_values": {
"low_auction_value": 2300,
"average_auction_value": 3600,
"high_auction_value": 4950,
"date_range": "8/29/2025"
}
}
```
The live `mileage_list` typically includes every band from `1` to `999999`. The example keeps three representative rows.