> ## 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 valorisation de marché
> Valorisation de véhicules en temps réel basée sur l'IA et des données de marché
## POST /v1/pricing/market-valuation
Obtenez des valorisations instantanées et précises basées sur des données de marché en temps réel, des ventes comparables, des tendances et l'état du véhicule. Alimenté par l'analyse IA de millions de transactions.
### Requête
```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
}
}'
```
### Corps de la requête
| Champ | Type | Requis | Description |
| ------------------------- | ------- | ------ | -------------------------------------------------- |
| `vehicle.vin` | string | Non\* | Numéro d'identification du véhicule (VIN) |
| `vehicle.year` | integer | Oui\* | Année de fabrication |
| `vehicle.make` | string | Oui\* | Marque du constructeur |
| `vehicle.model` | string | Oui\* | Modèle |
| `vehicle.trim` | string | Non | Finition |
| `vehicle.mileage` | integer | Oui | Kilométrage actuel |
| `location.zip_code` | string | Oui | Code postal pour la tarification régionale |
| `condition.overall` | string | Oui | `excellent`, `good`, `fair`, `poor` |
| `condition.inspection_id` | string | Non | Lien vers une inspection pour un état précis |
| `valuation_type` | string | Oui | `retail`, `trade_in`, `private_party`, `wholesale` |
\*VIN ou (year + make + model) requis
### Types de valorisation
| Type | Description | Cas d'usage |
| --------------- | ------------------------- | ------------------------------------------ |
| `retail` | Prix de vente concession | Prix de vente final par un concessionnaire |
| `trade_in` | Valeur de reprise | Ce que paie le concessionnaire |
| `private_party` | Valeur entre particuliers | Vente particulier à particulier |
| `wholesale` | Valeur en enchères | Vente de concessionnaire à concessionnaire |
### Réponse
```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
}
}
```
### Champs de réponse
| Champ | Type | Description |
| ---------------- | ------ | -------------------------------------------------- |
| `valuation_id` | string | Identifiant unique de valorisation |
| `base_value` | object | Valeur de base avant ajustements |
| `adjusted_value` | object | Valeur finale après ajustements |
| `adjustments` | array | Liste des facteurs d'ajustement |
| `market_demand` | string | `very_high`, `high`, `moderate`, `low`, `very_low` |
| `price_trend` | string | `increasing`, `stable`, `decreasing` |
| `days_to_sell` | object | Temps estimé de vente au prix donné |
| `comparables` | array | Véhicules similaires sur le marché |
| `confidence` | float | Score de confiance (0-1) |
### Facteurs de marché
**Impacts régionaux :**
• Marchés urbains vs ruraux
• Climat et conditions météo
• Réglementations et frais locaux
• Variations de la demande régionale
• Niveau de concurrence des concessionnaires
• Conditions économiques locales
**Plage typique :** ±5-15 % par rapport à la moyenne nationale
**Impacts de timing :**
• Printemps/Été : demande accrue pour cabriolets, sportives
• Automne/Hiver : demande accrue pour AWD/4WD
• Fin d'année : déstockage des concessionnaires
• Saison fiscale : activité d'achat accrue
• Périodes de fêtes : volume de transactions plus faible
**Plage typique :** ±3-8 % de variation saisonnière
**Ajustements :**
• \< 12k/an : +3 % à +8 %
• 12k-15k/an : référence (0 %)
• 15k-20k/an : -2 % à -5 %
• > 20k/an : -5 % à -15 %
• Très fort kilométrage (>100k) : -15 % à -30 %
**Règle de base :** $0.10-$0.30 par mile d'écart par rapport à la moyenne
**Couleurs populaires (premium) :**
• Noir, blanc, argent, gris : +1 % à +3 %
• Couleurs populaires régionales : +1 % à +2 %
**Couleurs moins populaires (décote) :**
• Couleurs vives/inusitées : -2 % à -5 %
• Beige/Marron (selon véhicule) : -1 % à -3 %
**Impact des options :** +2 % à +15 % pour des packs recherchés
### Stratégies de prix
**Objectif :** Vendre en 2 semaines
• Prix au niveau minimum ou en dessous
• Avantage de prix compétitif
• Trafic d'acheteurs élevé
• Négociation minimale
• Idéal pour vendeurs pressés
**Objectif :** Obtenir le meilleur prix
• Prix au niveau maximum
• Délai de vente plus long (60+ jours)
• Négociation plus importante
• Ciblage de profils d'acheteurs spécifiques
• Idéal pour vendeurs patients
**Objectif :** Équilibre prix/temps
• Prix au niveau moyen
• Vente attendue en 30-45 jours
• Négociation modérée
• Large attractivité
• Idéal pour la majorité des vendeurs
**Objectif :** Tester le marché
• Démarrer au prix max
• Suivre la réaction du marché
• Ajuster chaque semaine selon l'intérêt
• Approche flexible
• Idéal pour marchés incertains
### Réponses d'erreur
#### 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"
}
}
}
```
### Valorisation en lot
Pour valoriser plusieurs véhicules :
```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"}
}'
```
### Exemple d'intégration
```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"
}
}
```
**Astuce tarification :** Les valorisations sont valables 7 jours. Pour un inventaire actif, demandez une valorisation hebdomadaire pour rester aligné sur le marché.
**Volatilité du marché :** En périodes de forte volatilité (pénuries, changements économiques), les scores de confiance peuvent baisser et les fourchettes de prix s'élargir. Envisagez des valorisations plus fréquentes.