Market Valuation API - Steer Autos Documentation

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

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

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

Geographic Adjustments

Regional Market Impacts: • Urban vs. rural markets • Climate and weather patterns • State regulations and fees • Regional demand variations • Dealer competition levels • Local economic conditionsTypical Range: ±5-15% from national average

Seasonal Factors

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 volumeTypical Range: ±3-8% seasonal variation

Mileage Impact

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

Color & Options

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

Quick Sale Strategy

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

Maximum Value Strategy

Goal: Achieve highest price• Price at maximum value • Extended selling timeline (60+ days) • More negotiation required • Target specific buyer demographics • Best for patient sellers

Balanced Strategy

Goal: Optimal price/time balance• Price at average value • Expected sale in 30-45 days • Moderate negotiation • Broad buyer appeal • Best for most sellers

Test & Adjust

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

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

Bulk Valuation

For valuing multiple vehicles:

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

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

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.

API Documentation

​POST /v1/pricing/market-valuation

​Request

​Request Body

​Valuation Types

​Response

​Response Fields

​Market Factors

​Pricing Strategies

Quick Sale Strategy

Maximum Value Strategy

Balanced Strategy

Test & Adjust

​Error Responses

​400 Bad Request

​422 Unprocessable Entity

​Bulk Valuation

​Integration Example

​Webhooks

POST /v1/pricing/market-valuation

Request

Request Body

Valuation Types

Response

Response Fields

Market Factors

Pricing Strategies

Error Responses

400 Bad Request

422 Unprocessable Entity

Bulk Valuation

Integration Example

Webhooks