> ## 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.
# API de valuacion de mercado
> Valuacion de mercado en tiempo real con IA y datos en vivo
## POST /v1/pricing/market-valuation
Obtén valuaciones de mercado instantaneas y precisas basadas en datos en tiempo real, ventas comparables, tendencias de mercado y condicion del vehiculo. Impulsado por analisis de IA de millones de transacciones.
### 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\* | Numero de identificacion del vehiculo |
| `vehicle.year` | integer | Yes\* | Ano de fabricacion |
| `vehicle.make` | string | Yes\* | Fabricante |
| `vehicle.model` | string | Yes\* | Modelo |
| `vehicle.trim` | string | No | Version |
| `vehicle.mileage` | integer | Yes | Kilometraje actual |
| `location.zip_code` | string | Yes | Codigo postal para precios regionales |
| `condition.overall` | string | Yes | `excellent`, `good`, `fair`, `poor` |
| `condition.inspection_id` | string | No | Link a inspeccion para condicion precisa |
| `valuation_type` | string | Yes | `retail`, `trade_in`, `private_party`, `wholesale` |
\*Se requiere VIN o (year + make + model)
### Tipos de valuacion
| Type | Description | Typical Use Case |
| --------------- | ------------------------ | -------------------------- |
| `retail` | Precio retail del dealer | Precio de venta del dealer |
| `trade_in` | Valor de trade-in | Lo que pagaria el dealer |
| `private_party` | Venta entre particulares | Venta persona a persona |
| `wholesale` | Valor mayorista/subasta | Ventas dealer a dealer |
### 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
}
}
```
### Campos de respuesta
| Field | Type | Description |
| ---------------- | ------ | -------------------------------------------------- |
| `valuation_id` | string | Identificador unico de valuacion |
| `base_value` | object | Valor base antes de ajustes |
| `adjusted_value` | object | Valor final despues de ajustes |
| `adjustments` | array | Factores que afectan el valor |
| `market_demand` | string | `very_high`, `high`, `moderate`, `low`, `very_low` |
| `price_trend` | string | `increasing`, `stable`, `decreasing` |
| `days_to_sell` | object | Tiempo estimado de venta |
| `comparables` | array | Vehiculos similares en el mercado |
| `confidence` | float | Puntaje de confianza (0-1) |
### Factores de mercado
**Impactos regionales:**
• Mercados urbanos vs rurales
• Clima y patrones meteorologicos
• Regulaciones y fees estatales
• Variaciones de demanda regional
• Competencia entre dealers
• Condiciones economicas locales
**Rango tipico:** ±5-15% del promedio nacional
**Impactos de timing:**
• Primavera/Verano: Mayor demanda de convertibles y deportivos
• Otono/Invierno: Mayor demanda de AWD/4WD
• Fin de ano: Limpieza de inventario
• Temporada de impuestos: Mayor actividad de compra
• Periodos de vacaciones: Menor volumen de transacciones
**Rango tipico:** ±3-8% de variacion estacional
**Ajustes por kilometraje:**
• Debajo de 12k/ano: +3% a +8%
• 12k-15k/ano: Base (0%)
• 15k-20k/ano: -2% a -5%
• Arriba de 20k/ano: -5% a -15%
• Muy alto (>100k): -15% a -30%
**Regla general:** $0.10-$0.30 por milla de desviacion del promedio
**Colores populares (premium):**
• Negro, Blanco, Plateado, Gris: +1% a +3%
• Colores regionales populares: +1% a +2%
**Colores poco populares (descuento):**
• Colores brillantes/poco comunes: -2% a -5%
• Beige/Marron (varia por vehiculo): -1% a -3%
**Impacto de opciones:** +2% a +15% para paquetes deseables
### Estrategias de precios
**Objetivo:** Vender en 2 semanas
• Precio en minimo o por debajo
• Ventaja competitiva de precio
• Alto trafico de compradores
• Negociacion minima
• Ideal para vendedores con urgencia
**Objetivo:** Lograr el precio mas alto
• Precio en maximo valor
• Timeline extendido (60+ dias)
• Mas negociacion
• Buyer targeting especifico
• Ideal para vendedores pacientes
**Objetivo:** Balance precio/tiempo
• Precio en valor promedio
• Venta esperada en 30-45 dias
• Negociacion moderada
• Atractivo amplio
• Ideal para la mayoria
**Objetivo:** Test de mercado
• Comienza en valor maximo
• Monitorea respuesta del mercado
• Ajusta semanalmente segun interes
• Enfoque flexible
• Ideal para mercados inciertos
### Respuestas de error
#### 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"
}
}
}
```
### Valuacion masiva
Para valuar multiples vehiculos:
```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"}
}'
```
### Ejemplo de integracion
```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"
}
}
```
**Tip de precios:** Las valuaciones son validas por 7 dias. Para inventario activo, solicita valuaciones semanales para mantener competitividad.
**Volatilidad de mercado:** En periodos de alta volatilidad, los scores de confianza pueden ser mas bajos y los rangos mas amplios. Considera valuaciones mas frecuentes.