API de valuacion de mercado - Steer Autos Documentation

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

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

{
  "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

Ajustes geograficos

Impactos regionales: • Mercados urbanos vs rurales • Clima y patrones meteorologicos • Regulaciones y fees estatales • Variaciones de demanda regional • Competencia entre dealers • Condiciones economicas localesRango tipico: ±5-15% del promedio nacional

Factores estacionales

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 transaccionesRango tipico: ±3-8% de variacion estacional

Impacto de kilometraje

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

Color y opciones

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

Estrategia de venta rapida

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

Estrategia de maximo valor

Objetivo: Lograr el precio mas alto• Precio en maximo valor • Timeline extendido (60+ dias) • Mas negociacion • Buyer targeting especifico • Ideal para vendedores pacientes

Estrategia balanceada

Objetivo: Balance precio/tiempo• Precio en valor promedio • Venta esperada en 30-45 dias • Negociacion moderada • Atractivo amplio • Ideal para la mayoria

Probar y ajustar

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

{
  "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

{
  "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:

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

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

{
  "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.

Documentacion de la API

​POST /v1/pricing/market-valuation

​Request

​Request Body

​Tipos de valuacion

​Response

​Campos de respuesta

​Factores de mercado

​Estrategias de precios

Estrategia de venta rapida

Estrategia de maximo valor

Estrategia balanceada

Probar y ajustar

​Respuestas de error

​400 Bad Request

​422 Unprocessable Entity

​Valuacion masiva

​Ejemplo de integracion

​Webhooks

POST /v1/pricing/market-valuation

Request

Request Body

Tipos de valuacion

Response

Campos de respuesta

Factores de mercado

Estrategias de precios

Respuestas de error

400 Bad Request

422 Unprocessable Entity

Valuacion masiva

Ejemplo de integracion

Webhooks