> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steerai.autos/llms.txt
> Use this file to discover all available pages before exploring further.
# Market Valuation API
> Real-time vehicle market valuation powered by AI and live market data
## POST /v1/pricing/market-valuation
Get instant, accurate vehicle market valuations based on real-time market data, comparable sales, market trends, and vehicle condition. Powered by AI analysis of millions of transactions.
### Request
```bash theme={null}
curl -X POST "https://api.steerai.autos/v1/pricing/market-valuation" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vehicle": {
"vin": "1HGBH41JXMN109186",
"year": 2021,
"make": "Honda",
"model": "Civic",
"trim": "EX",
"mileage": 45000,
"exterior_color": "Modern Steel Metallic",
"interior_color": "Black",
"transmission": "CVT",
"drivetrain": "FWD",
"engine": "2.0L 4-Cylinder"
},
"location": {
"zip_code": "90210",
"city": "Beverly Hills",
"state": "CA",
"country": "US"
},
"condition": {
"overall": "good",
"inspection_id": "vis_1234567890abcdef"
},
"valuation_type": "retail",
"options": {
"include_comparables": true,
"include_market_trends": true,
"include_depreciation_forecast": true
}
}'
```
### Request Body
| Field | Type | Required | Description |
| ------------------------- | ------- | -------- | -------------------------------------------------- |
| `vehicle.vin` | string | No\* | Vehicle Identification Number |
| `vehicle.year` | integer | Yes\* | Manufacturing year |
| `vehicle.make` | string | Yes\* | Manufacturer name |
| `vehicle.model` | string | Yes\* | Model name |
| `vehicle.trim` | string | No | Trim level |
| `vehicle.mileage` | integer | Yes | Current mileage |
| `location.zip_code` | string | Yes | ZIP/postal code for regional pricing |
| `condition.overall` | string | Yes | `excellent`, `good`, `fair`, `poor` |
| `condition.inspection_id` | string | No | Link to inspection for precise condition |
| `valuation_type` | string | Yes | `retail`, `trade_in`, `private_party`, `wholesale` |
\*Either VIN or (year + make + model) required
### Valuation Types
| Type | Description | Typical Use Case |
| --------------- | ----------------------- | ----------------------------- |
| `retail` | Dealer retail price | What dealer would sell for |
| `trade_in` | Trade-in offer value | What dealer would pay |
| `private_party` | Private sale value | Individual-to-individual sale |
| `wholesale` | Auction/wholesale value | Dealer-to-dealer sales |
### Response
```json theme={null}
{
"status": "success",
"data": {
"valuation_id": "val_1234567890abcdef",
"vehicle": {
"vin": "1HGBH41JXMN109186",
"year": 2021,
"make": "Honda",
"model": "Civic",
"trim": "EX",
"mileage": 45000,
"body_style": "Sedan",
"engine": "2.0L 4-Cylinder",
"transmission": "CVT",
"drivetrain": "FWD"
},
"location": {
"zip_code": "90210",
"city": "Beverly Hills",
"state": "CA",
"market_region": "Southern California"
},
"valuation": {
"valuation_type": "retail",
"currency": "USD",
"base_value": {
"min": 22500,
"average": 24800,
"max": 26500,
"confidence": 0.92
},
"adjusted_value": {
"min": 22100,
"average": 24300,
"max": 26000,
"confidence": 0.89
},
"adjustments": [
{
"factor": "mileage",
"description": "Below average mileage for age",
"impact": 500,
"impact_percentage": 2.0,
"direction": "positive"
},
{
"factor": "location",
"description": "High demand market",
"impact": 800,
"impact_percentage": 3.2,
"direction": "positive"
},
{
"factor": "color",
"description": "Popular color choice",
"impact": 200,
"impact_percentage": 0.8,
"direction": "positive"
},
{
"factor": "condition",
"description": "Good condition with minor wear",
"impact": -1000,
"impact_percentage": -4.0,
"direction": "negative"
}
],
"total_adjustment": 500,
"adjustment_percentage": 2.0
},
"market_analysis": {
"days_to_sell": {
"estimate": 28,
"range": {
"min": 18,
"max": 42
}
},
"market_demand": "high",
"demand_score": 8.2,
"inventory_level": "below_average",
"price_trend": "stable",
"price_trend_percentage": 0.5,
"seasonal_factor": {
"current_season": "spring",
"impact": "positive",
"adjustment_percentage": 2.5,
"description": "Peak buying season for sedans"
}
},
"comparables": [
{
"listing_id": "comp_001",
"source": "dealer_listing",
"year": 2021,
"make": "Honda",
"model": "Civic",
"trim": "EX",
"mileage": 42000,
"price": 24995,
"location": "Los Angeles, CA",
"distance_miles": 12,
"days_on_market": 15,
"similarity_score": 0.95
},
{
"listing_id": "comp_002",
"source": "recent_sale",
"year": 2021,
"make": "Honda",
"model": "Civic",
"trim": "EX",
"mileage": 48000,
"price": 23800,
"location": "Santa Monica, CA",
"distance_miles": 8,
"sale_date": "2024-01-10",
"similarity_score": 0.91
},
{
"listing_id": "comp_003",
"source": "dealer_listing",
"year": 2021,
"make": "Honda",
"model": "Civic",
"trim": "Sport",
"mileage": 43000,
"price": 25500,
"location": "Pasadena, CA",
"distance_miles": 22,
"days_on_market": 8,
"similarity_score": 0.88
}
],
"depreciation_forecast": {
"current_value": 24300,
"original_msrp": 28500,
"total_depreciation": 4200,
"depreciation_percentage": 14.7,
"annual_depreciation_rate": 5.2,
"forecast": [
{
"year": 2024,
"estimated_value": 24300,
"confidence": 0.89
},
{
"year": 2025,
"estimated_value": 22100,
"confidence": 0.82
},
{
"year": 2026,
"estimated_value": 19800,
"confidence": 0.73
},
{
"year": 2027,
"estimated_value": 17600,
"confidence": 0.65
}
]
},
"alternative_valuations": {
"trade_in": {
"min": 19500,
"average": 21200,
"max": 22500
},
"private_party": {
"min": 21000,
"average": 23100,
"max": 24800
},
"wholesale": {
"min": 18000,
"average": 19800,
"max": 21000
}
},
"confidence_factors": {
"overall_confidence": 0.89,
"factors": [
{
"factor": "comparable_data",
"confidence": 0.95,
"weight": 0.40,
"description": "Strong comparable sales data available"
},
{
"factor": "market_data",
"confidence": 0.88,
"weight": 0.30,
"description": "Robust market statistics for region"
},
{
"factor": "vehicle_history",
"confidence": 0.85,
"weight": 0.20,
"description": "Complete vehicle history available"
},
{
"factor": "condition_assessment",
"confidence": 0.80,
"weight": 0.10,
"description": "Based on reported condition"
}
]
},
"created_at": "2024-01-15T13:00:00Z",
"expires_at": "2024-01-22T13:00:00Z",
"valid_days": 7
},
"meta": {
"request_id": "req_val_abc123",
"processing_time": 1.234,
"data_sources": ["dealer_listings", "auction_results", "private_sales", "market_indices"],
"comparables_analyzed": 47,
"market_transactions_analyzed": 1285
}
}
```
### Response Fields
| Field | Type | Description |
| ---------------- | ------ | -------------------------------------------------- |
| `valuation_id` | string | Unique valuation identifier |
| `base_value` | object | Baseline market value before adjustments |
| `adjusted_value` | object | Final value after all adjustments |
| `adjustments` | array | List of factors affecting value |
| `market_demand` | string | `very_high`, `high`, `moderate`, `low`, `very_low` |
| `price_trend` | string | `increasing`, `stable`, `decreasing` |
| `days_to_sell` | object | Estimated time to sell at given price |
| `comparables` | array | Similar vehicles in the market |
| `confidence` | float | Confidence score (0-1) |
### Market Factors
**Regional Market Impacts:**
• Urban vs. rural markets
• Climate and weather patterns
• State regulations and fees
• Regional demand variations
• Dealer competition levels
• Local economic conditions
**Typical Range:** ±5-15% from national average
**Timing Impacts:**
• Spring/Summer: Higher demand for convertibles, sports cars
• Fall/Winter: Higher demand for AWD/4WD vehicles
• Year-end: Dealer inventory clearing
• Tax season: Increased buyer activity
• Holiday periods: Lower transaction volume
**Typical Range:** ±3-8% seasonal variation
**Mileage Adjustments:**
• Below 12k/year: +3% to +8%
• 12k-15k/year: Baseline (0%)
• 15k-20k/year: -2% to -5%
• Above 20k/year: -5% to -15%
• Very high mileage (>100k): -15% to -30%
**Rule of Thumb:** $0.10-$0.30 per mile deviation from average
**Popular Colors (Premium):**
• Black, White, Silver, Gray: +1% to +3%
• Popular regional colors: +1% to +2%
**Unpopular Colors (Discount):**
• Bright/unusual colors: -2% to -5%
• Beige/Brown (varies by vehicle): -1% to -3%
**Options Impact:** +2% to +15% for desirable packages
### Pricing Strategies
**Goal:** Sell within 2 weeks
• Price at or below minimum value
• Competitive pricing advantage
• High buyer traffic
• Minimal negotiation needed
• Best for time-sensitive sellers
**Goal:** Achieve highest price
• Price at maximum value
• Extended selling timeline (60+ days)
• More negotiation required
• Target specific buyer demographics
• Best for patient sellers
**Goal:** Optimal price/time balance
• Price at average value
• Expected sale in 30-45 days
• Moderate negotiation
• Broad buyer appeal
• Best for most sellers
**Goal:** Market testing
• Start at max value
• Monitor market response
• Adjust weekly based on interest
• Flexible pricing approach
• Best for uncertain markets
### Error Responses
#### 400 Bad Request
```json theme={null}
{
"status": "error",
"error": {
"code": "INVALID_VIN",
"message": "The provided VIN is invalid or not found in database",
"type": "validation_error",
"field": "vehicle.vin"
}
}
```
#### 422 Unprocessable Entity
```json theme={null}
{
"status": "error",
"error": {
"code": "INSUFFICIENT_MARKET_DATA",
"message": "Not enough market data available for this vehicle in the specified region",
"type": "data_error",
"details": {
"comparables_found": 2,
"minimum_required": 5,
"suggestion": "Try expanding search radius or using national valuation"
}
}
}
```
### Bulk Valuation
For valuing multiple vehicles:
```bash theme={null}
curl -X POST "https://api.steerai.autos/v1/pricing/bulk-valuation" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vehicles": [
{"vin": "1HGBH41JXMN109186", "mileage": 45000},
{"vin": "2FMDK3KC8DBA12345", "mileage": 62000},
{"vin": "5XYKT3A68FG123456", "mileage": 38000}
],
"valuation_type": "trade_in",
"location": {"zip_code": "90210"}
}'
```
### Integration Example
```javascript theme={null}
const SteerAI = require('@steerai/sdk');
const client = new SteerAI('YOUR_API_KEY');
async function valueVehicle(vin, mileage, zipCode) {
try {
const valuation = await client.pricing.marketValuation({
vehicle: { vin, mileage },
location: { zip_code: zipCode },
condition: { overall: 'good' },
valuation_type: 'retail',
options: {
include_comparables: true,
include_market_trends: true
}
});
console.log(`Retail Value: $${valuation.data.valuation.adjusted_value.average}`);
console.log(`Days to Sell: ${valuation.data.market_analysis.days_to_sell.estimate}`);
console.log(`Market Demand: ${valuation.data.market_analysis.market_demand}`);
return valuation;
} catch (error) {
console.error('Valuation error:', error.message);
}
}
valueVehicle('1HGBH41JXMN109186', 45000, '90210');
```
### Webhooks
```json theme={null}
{
"event": "market_valuation.completed",
"timestamp": "2024-01-15T13:00:05Z",
"data": {
"valuation_id": "val_1234567890abcdef",
"vehicle": {
"year": 2021,
"make": "Honda",
"model": "Civic"
},
"valuation_type": "retail",
"average_value": 24300,
"confidence": 0.89,
"market_demand": "high"
}
}
```
**Pricing Tip:** Valuations are valid for 7 days. For active inventory, request fresh valuations weekly to stay competitive with current market conditions.
**Market Volatility:** During periods of high market volatility (e.g., supply shortages, economic shifts), confidence scores may be lower and price ranges wider. Consider more frequent valuations during these periods.