API de valorisation de marché - Steer Autos Documentation

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

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

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

Ajustements géographiques

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 localesPlage typique : ±5-15 % par rapport à la moyenne nationale

Facteurs saisonniers

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 faiblePlage typique : ±3-8 % de variation saisonnière

Impact du kilométrage

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

Couleur et options

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

Stratégie vente rapide

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

Stratégie valeur maximale

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

Stratégie équilibrée

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

Tester et ajuster

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

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

Valorisation en lot

Pour valoriser plusieurs véhicules :

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

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

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.

Documentation API

​POST /v1/pricing/market-valuation

​Requête

​Corps de la requête

​Types de valorisation

​Réponse

​Champs de réponse

​Facteurs de marché

​Stratégies de prix

Stratégie vente rapide

Stratégie valeur maximale

Stratégie équilibrée

Tester et ajuster

​Réponses d’erreur

​400 Bad Request

​422 Unprocessable Entity

​Valorisation en lot

​Exemple d’intégration

​Webhooks

POST /v1/pricing/market-valuation

Requête

Corps de la requête

Types de valorisation

Réponse

Champs de réponse

Facteurs de marché

Stratégies de prix

Réponses d’erreur

400 Bad Request

422 Unprocessable Entity

Valorisation en lot

Exemple d’intégration

Webhooks