API für Marktbewertung - Steer Autos Documentation

POST /v1/pricing/market-valuation

Erhalten Sie sofortige, präzise Marktwerte auf Basis von Echtzeit-Marktdaten, vergleichbaren Verkäufen, Markttrends und Fahrzeugzustand. Gestützt auf KI-Analyse von Millionen Transaktionen.

Anfrage

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

Anfrage-Body

Feld	Typ	Erforderlich	Beschreibung
`vehicle.vin`	string	Nein*	Fahrzeug-Identifikationsnummer (VIN)
`vehicle.year`	integer	Ja*	Baujahr
`vehicle.make`	string	Ja*	Hersteller
`vehicle.model`	string	Ja*	Modell
`vehicle.trim`	string	Nein	Ausstattungslinie
`vehicle.mileage`	integer	Ja	Aktueller Kilometerstand
`location.zip_code`	string	Ja	Postleitzahl für regionale Preisfindung
`condition.overall`	string	Ja	`excellent`, `good`, `fair`, `poor`
`condition.inspection_id`	string	Nein	Verknüpfung zur Inspektion für präzisen Zustand
`valuation_type`	string	Ja	`retail`, `trade_in`, `private_party`, `wholesale`

*Entweder VIN oder (year + make + model) erforderlich

Bewertungsarten

Typ	Beschreibung	Typischer Anwendungsfall
`retail`	Händlerverkaufspreis	Wofür der Händler verkaufen würde
`trade_in`	Inzahlungnahmewert	Wofür der Händler zahlen würde
`private_party`	Privatverkaufspreis	Verkauf von Privat zu Privat
`wholesale`	Auktions-/Großhandelswert	Händler-zu-Händler-Verkäufe

Antwort

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

Antwortfelder

Feld	Typ	Beschreibung
`valuation_id`	string	Eindeutige Bewertungskennung
`base_value`	object	Basismarktwert vor Anpassungen
`adjusted_value`	object	Endwert nach allen Anpassungen
`adjustments`	array	Liste der Faktoren, die den Wert beeinflussen
`market_demand`	string	`very_high`, `high`, `moderate`, `low`, `very_low`
`price_trend`	string	`increasing`, `stable`, `decreasing`
`days_to_sell`	object	Geschätzte Verkaufsdauer zum angegebenen Preis
`comparables`	array	Vergleichbare Fahrzeuge am Markt
`confidence`	float	Vertrauensscore (0-1)

Marktfaktoren

Geografische Anpassungen

Regionale Markteinflüsse: • Urbane vs. ländliche Märkte • Klima- und Wetterbedingungen • Staatliche Vorschriften und Gebühren • Regionale Nachfrageunterschiede • Wettbewerbsintensität der Händler • Lokale wirtschaftliche BedingungenTypischer Bereich: ±5-15% vom nationalen Durchschnitt

Saisonale Faktoren

Zeiteinflüsse: • Frühjahr/Sommer: Höhere Nachfrage nach Cabriolets, Sportwagen • Herbst/Winter: Höhere Nachfrage nach AWD/4WD-Fahrzeugen • Jahresende: Händler räumen Lagerbestände • Steuerzeit: Erhöhte Käuferaktivität • Ferienzeiten: Geringeres TransaktionsvolumenTypischer Bereich: ±3-8% saisonale Variation

Einfluss der Laufleistung

Laufleistungsanpassungen: • Unter 12k/Jahr: +3% bis +8% • 12k-15k/Jahr: Basislinie (0%) • 15k-20k/Jahr: -2% bis -5% • Über 20k/Jahr: -5% bis -15% • Sehr hohe Laufleistung (>100k): -15% bis -30%Faustregel:

0,10-

0,30 pro Meile Abweichung vom Durchschnitt

Farbe & Optionen

Beliebte Farben (Aufpreis): • Schwarz, Weiß, Silber, Grau: +1% bis +3% • Regional beliebte Farben: +1% bis +2%Unbeliebte Farben (Abschlag): • Knallige/ungewöhnliche Farben: -2% bis -5% • Beige/Braun (fahrzeugspezifisch): -1% bis -3%Optionen-Einfluss: +2% bis +15% für begehrte Pakete

Preisstrategien

Schnellverkaufsstrategie

Ziel: Verkauf innerhalb von 2 Wochen• Preis am oder unter dem Mindestwert • Wettbewerbsvorteil durch Preis • Hoher Käuferandrang • Minimale Verhandlung nötig • Ideal für zeitkritische Verkäufer

Maximalwertstrategie

Ziel: Höchstpreis erzielen• Preis am Maximalwert • Längerer Verkaufszeitraum (60+ Tage) • Mehr Verhandlung notwendig • Zielgruppe gezielt ansprechen • Ideal für geduldige Verkäufer

Ausgewogene Strategie

Ziel: Optimales Preis/Zeit-Verhältnis• Preis am Durchschnittswert • Erwarteter Verkauf in 30–45 Tagen • Moderate Verhandlung • Breite Käuferansprache • Ideal für die meisten Verkäufer

Test & Anpassung

Ziel: Markt testen• Start am Maximalwert • Marktreaktion beobachten • Wöchentlich anpassen • Flexible Preisstrategie • Ideal für unsichere Märkte

Fehlerantworten

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-Bewertung

Für die Bewertung mehrerer Fahrzeuge:

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

Integrationsbeispiel

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

Preistipp: Bewertungen sind 7 Tage gültig. Für aktiven Bestand wöchentlich neue Bewertungen anfordern, um konkurrenzfähig zu bleiben.

Marktvolatilität: In Phasen hoher Marktvolatilität (z. B. Angebotsengpässe, wirtschaftliche Veränderungen) können Vertrauensscores niedriger und Preisspannen breiter sein. Erwägen Sie in solchen Zeiten häufigere Bewertungen.

API-Dokumentation

​POST /v1/pricing/market-valuation

​Anfrage

​Anfrage-Body

​Bewertungsarten

​Antwort

​Antwortfelder

​Marktfaktoren

​Preisstrategien

Schnellverkaufsstrategie

Maximalwertstrategie

Ausgewogene Strategie

Test & Anpassung

​Fehlerantworten

​400 Bad Request

​422 Unprocessable Entity

​Bulk-Bewertung

​Integrationsbeispiel

​Webhooks

POST /v1/pricing/market-valuation

Anfrage

Anfrage-Body

Bewertungsarten

Antwort

Antwortfelder

Marktfaktoren

Preisstrategien

Fehlerantworten

400 Bad Request

422 Unprocessable Entity

Bulk-Bewertung

Integrationsbeispiel

Webhooks