# Price Prediction

> Full reference for the predict_price_with_comparables tool — ML-based vehicle price prediction with comparable active market listings for US vehicles.

Predict a vehicle's market price using its VIN, along with a set of comparable active listings for market context. The prediction uses MarketCheck's ML-based pricing model, adjusted for mileage, location, and dealer type.



## Overview

| Property | Value    |
|----------|----------|
| Tool name | `predict_price_with_comparables` |
| Market | US |
| Required | VIN (17 characters) |
| API endpoint | `GET /v2/predict/car/us/marketcheck_price/comparables` |




## Parameters

| Parameter   | Type        | Default     | Required    | Description |
|-------------|-------------|-------------|-------------|-------------|
| `vin` | string | — | **Yes** | 17-character Vehicle Identification Number |
| `miles` | int | `50000` | No | Total miles driven on the vehicle |
| `dealer_type` | string | `"franchise"` | No | `"franchise"` or `"independent"` |
| `zip` | string | `"50501"` | No | ZIP code for location-based pricing (default: Des Moines, IA) |
| `city` | string | — | No | City name — takes precedence over `zip` when combined with `state` |
| `state` | string | — | No | 2-letter state code — required when using `city` |
| `is_certified` | bool | `false` | No | Whether the vehicle is certified pre-owned (CPO) |




### Location Logic

The location determines which comparable listings are used for the prediction:

- If both `city` and `state` are provided, they take precedence over `zip`
- If only `zip` is provided (or neither), `zip` is used (default: `50501` — Des Moines, IA)
- Location significantly affects the predicted price due to regional market differences



## Response

The tool returns a JSON object containing:

- **Predicted price** — MarketCheck's estimated market value based on ML models
- **MSRP** — Manufacturer's Suggested Retail Price for the vehicle
- **Comparable listings** — Active vehicles in the market matching the VIN's specifications, each with price, mileage, dealer info, and location



## Use Cases



### Basic price prediction

```text
predict_price_with_comparables(
  vin="1HGCV1F34JA123456"
)
```



### Location-specific valuation

```text
predict_price_with_comparables(
  vin="1HGCV1F34JA123456",
  miles=35000,
  zip="90210",
  dealer_type="franchise"
)
```



### Certified pre-owned valuation

```text
predict_price_with_comparables(
  vin="1HGCV1F34JA123456",
  miles=28000,
  is_certified=true,
  city="Los Angeles",
  state="CA"
)
```



### Independent dealer pricing

```text
predict_price_with_comparables(
  vin="1HGCV1F34JA123456",
  miles=65000,
  dealer_type="independent",
  zip="77001"
)
```



## Common Workflow

For a comprehensive vehicle valuation, combine this tool with VIN decoding and history:

1. **Decode the VIN** — `decode_vin_neovin(vin=...)` to confirm vehicle specs and MSRP
2. **Predict price** — `predict_price_with_comparables(vin=..., miles=..., zip=...)` for market value and comparables
3. **Check history** — `get_car_history(vin=...)` to review past listing prices and dealer activity



## See Also

- [VIN Decode](/docs/get-started/api/mcp/tools/decode-vin) — Decode VIN for full specs before pricing
- [Car History](/docs/get-started/api/mcp/tools/car-history) — Historical listing data for a VIN
- [Sold Summary](/docs/get-started/api/mcp/tools/sold-summary) — Aggregate sold vehicle analytics (Enterprise only)