> ## 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 für Marktbewertung

> Echtzeit-Fahrzeugbewertungen mit KI und Live-Marktdaten

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

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

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

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

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

<AccordionGroup>
  <Accordion icon="location-dot" title="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 Bedingungen

    **Typischer Bereich:** ±5-15% vom nationalen Durchschnitt
  </Accordion>

  <Accordion icon="calendar" title="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 Transaktionsvolumen

    **Typischer Bereich:** ±3-8% saisonale Variation
  </Accordion>

  <Accordion icon="gauge" title="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
  </Accordion>

  <Accordion icon="palette" title="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
  </Accordion>
</AccordionGroup>

### Preisstrategien

<CardGroup cols={2}>
  <Card title="Schnellverkaufsstrategie" icon="bolt">
    **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
  </Card>

  <Card title="Maximalwertstrategie" icon="dollar-sign">
    **Ziel:** Höchstpreis erzielen

    • Preis am Maximalwert
    • Längerer Verkaufszeitraum (60+ Tage)
    • Mehr Verhandlung notwendig
    • Zielgruppe gezielt ansprechen
    • Ideal für geduldige Verkäufer
  </Card>

  <Card title="Ausgewogene Strategie" icon="scale-balanced">
    **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
  </Card>

  <Card title="Test & Anpassung" icon="chart-line">
    **Ziel:** Markt testen

    • Start am Maximalwert
    • Marktreaktion beobachten
    • Wöchentlich anpassen
    • Flexible Preisstrategie
    • Ideal für unsichere Märkte
  </Card>
</CardGroup>

### Fehlerantworten

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

Für die Bewertung mehrerer Fahrzeuge:

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

### Integrationsbeispiel

```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>
  **Preistipp:** Bewertungen sind 7 Tage gültig. Für aktiven Bestand wöchentlich neue Bewertungen anfordern, um konkurrenzfähig zu bleiben.
</Tip>

<Warning>
  **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.
</Warning>