CarHunt Analyses API

openapi: 3.2.0
info:
  title: CarHunt Pro Analyses API
  description: 'API de sourcing automobile CarHunt Pro : recherche multi-critères dans

    plus d’un million d''annonces actives agrégées depuis 6

    sources. Un cycle complet d''actualisation du catalogue est lancé toutes les

    4 heures. Chaque annonce dispose d''un score de

    sous-cote et de médianes de marché. Les critères des watchlists sont évalués toutes les

    10 minutes sur le catalogue déjà collecté, puis les

    webhooks sont notifiés après détection. ### Authentification

    Créez une clé API dans votre espace app.carhunt.fr

    (Réglages → API, offre Business ou API Analyste attribuée), puis transmettez-la sur chaque requête :


    Authorization: Bearer chp_live_…


    ### Quotas

    Le plan Business inclut un quota mensuel de **véhicules**. L''offre API Analyste,

    attribuée individuellement, inclut 1 000 **analyses** et 5 000 **véhicules**

    par mois calendaire UTC. `GET /v1/usage` expose les deux soldes. Chaque véhicule renvoyé par la recherche ou livré par webhook est décompté

    une fois. `POST /v1/estimate` et `GET /v1/listings/{listing_id}/analysis`

    consomment chacun une analyse si une réponse exploitable est produite ; les

    trois comparables inclus ne débitent pas de véhicules. Une cohorte de moins

    de cinq annonces rend 422 sans débit. Les crédits d''analyse prépayés prennent

    le relais après le quota mensuel et n''expirent pas. Pour proposer 3 à 5 alternatives, appelez `GET /v1/listings/search` avec

    `page_size=3` à `5`, budget (`price_max`) et critères du client ; le nombre

    de véhicules effectivement renvoyés est débité. Aucun classement personnalisé

    ni garantie de disponibilité chez l''annonceur n''est implicite. Rate-limit : 60 req/min par clé. ### Synchronisation des annonces importées

    `GET /v1/listings/changes` accepte jusqu''à 100 identifiants CarHunt dans `ids`. La recherche fournit `sync_until` pour initialiser le suivi sans nouvel import. Sans date, le flux peut réinitialiser un lot (véhicules décomptés). Transmettez

    `updated_since` avec le `sync_until` du dernier lot traité : seuls les véhicules

    réellement modifiés sont renvoyés et décomptés. Une réponse vide ne consomme rien. Chaque élément expose `last_modified_at`, `status` et la fiche `listing`. Les statuts `inactive` et `deleted` permettent de retirer les annonces du catalogue

    client ; `deleted` a une fiche nulle et ne signifie pas vendu. `unknown_ids` ne

    prouve pas un retrait. Revisites et recalculs de score ne déclenchent pas d''édition. Le suivi commence à `tracking_started_at` : une date antérieure rend 409 et exige

    une réinitialisation sans date. Un lot dépassant le solde rend 429 sans décompte. Le paramètre `since` de la recherche continue à servir aux **nouvelles** annonces. ### Estimation et historique

    `POST /v1/estimate` accepte marque, modèle, année, kilométrage et des filtres

    facultatifs (énergie, boîte, motorisation, finition), sans annonce à résoudre. Les quartiles et la médiane portent sur les **prix demandés** d''annonces actives

    comparables, pas sur les transactions. La cohorte est échantillonnée à 2 000

    annonces récentes au maximum ; `sample_truncated` le signale. Les repères de

    négociation sont statistiques : ils ne tiennent pas compte de l''état réel. L''historique et la volatilité de `GET /v1/listings/{listing_id}/analysis`

    concernent **cette annonce**, pas l''ensemble du marché. L''historique peut être vide. `history_status` distingue `unavailable` (aucune observation sur la période demandée),

    `no_change_recorded` (aucune variation enregistrée depuis la première observation)

    et `price_changed`. `source_url` et `current_price` concernent l''annonce analysée. La collecte d''historique ayant débuté en juin 2026, une absence de variation

    enregistrée ne permet pas de conclure sur les prix antérieurs. Exemple d''estimation (prix en euros, kilométrage en km) :


    ```json

    {"make":"RENAULT","model":"CLIO","year":2020,"mileage":50000,"energy":"Essence","asking_price":13500}

    ```


    ### Couverture

    Le catalogue cible les annonces automobiles d''occasion en France.'
  contact:
    name: CarHunt Pro
    url: https://app.carhunt.fr/
    email: contact@carhunt.fr
  version: 1.0.0
servers:
- url: /public-api
- url: https://api-pro.carhunt.fr
  description: Production
- url: https://api-pro-stage.carhunt.fr
  description: Staging
tags:
- name: Analyses
paths:
  /v1/estimate:
    post:
      tags:
      - Analyses
      summary: Estimer un véhicule sans annonce
      description: Une analyse utile = 1 crédit ; échec/échantillon insuffisant = 0. Les comparables sont inclus.
      operationId: estimate_vehicle_v1_estimate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EstimateIn'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EstimateOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/listings/{listing_id}/analysis:
    get:
      tags:
      - Analyses
      summary: Estimation, historique et négociation d'une annonce
      description: Historique et volatilité de l'annonce ; la cohorte de marché reste distincte.
      operationId: listing_analysis_v1_listings__listing_id__analysis_get
      parameters:
      - name: listing_id
        in: path
        required: true
        schema:
          type: string
          title: Listing Id
      - name: history_days
        in: query
        required: false
        schema:
          type: integer
          maximum: 3650
          minimum: 1
          default: 365
          title: History Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListingAnalysisOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    EstimateOut:
      properties:
        generated_at:
          type: string
          format: date-time
          title: Generated At
          description: Date UTC de génération du rapport
        make:
          type: string
          title: Make
        model:
          type: string
          title: Model
        year:
          type: integer
          title: Year
        mileage:
          type: integer
          title: Mileage
        energy:
          anyOf:
          - type: string
          - type: 'null'
          title: Energy
        gearbox:
          anyOf:
          - type: string
          - type: 'null'
          title: Gearbox
        motorization:
          anyOf:
          - type: string
          - type: 'null'
          title: Motorization
        finition:
          anyOf:
          - type: string
          - type: 'null'
          title: Finition
        year_window:
          type: integer
          title: Year Window
          description: Écart maximal d'année retenu autour de l'année demandée
        mileage_window_km:
          type: integer
          title: Mileage Window Km
        comparable_count:
          type: integer
          title: Comparable Count
          description: Nombre d'annonces échantillonnées, au plus 2 000
        sample_truncated:
          type: boolean
          title: Sample Truncated
        good_price:
          type: integer
          title: Good Price
          description: Premier quartile des prix demandés, pas une valeur de transaction
        market_median:
          type: integer
          title: Market Median
          description: Médiane des prix demandés
        high_price:
          type: integer
          title: High Price
          description: Troisième quartile des prix demandés
        comparables:
          items:
            $ref: '#/components/schemas/ComparableOut'
          type: array
          title: Comparables
        negotiation:
          anyOf:
          - $ref: '#/components/schemas/NegotiationOut'
          - type: 'null'
        analysis_units_charged:
          type: integer
          title: Analysis Units Charged
          default: 1
        vehicle_units_charged:
          type: integer
          title: Vehicle Units Charged
          description: Les 3 comparables sont inclus dans l'analyse
          default: 0
      type: object
      required:
      - make
      - model
      - year
      - mileage
      - year_window
      - mileage_window_km
      - comparable_count
      - sample_truncated
      - good_price
      - market_median
      - high_price
      - comparables
      title: EstimateOut
    NegotiationOut:
      properties:
        asking_price:
          type: integer
          title: Asking Price
        opening_offer:
          type: integer
          title: Opening Offer
          description: Plus petit du prix demandé et du premier quartile observé
        target_ceiling:
          type: integer
          title: Target Ceiling
          description: Plus petit du prix demandé et de la médiane observée
        difference_to_median:
          type: integer
          title: Difference To Median
        basis:
          type: string
          title: Basis
          default: Repère statistique sur les annonces comparables ; état et inspection du véhicule non vérifiés.
      type: object
      required:
      - asking_price
      - opening_offer
      - target_ceiling
      - difference_to_median
      title: NegotiationOut
    ListingAnalysisOut:
      properties:
        listing_id:
          type: string
          title: Listing Id
        source_url:
          type: string
          title: Source Url
          description: Lien de l'annonce analysée chez sa source d'origine
        current_price:
          type: integer
          title: Current Price
          description: Prix courant de l'annonce analysée, en euros
        history_status:
          type: string
          title: History Status
          description: 'unavailable : aucune observation de prix disponible sur la période demandée ; no_change_recorded : aucune variation enregistrée depuis la première observation ; price_changed : au moins une variation enregistrée. Ne préjuge pas des variations antérieures à la collecte CarHunt.'
        estimate:
          $ref: '#/components/schemas/EstimateOut'
        price_history:
          type: object
          title: Price History
          description: Historique de cette annonce uniquement, lorsqu'il existe
        price_volatility:
          type: object
          title: Price Volatility
          description: Volatilité de cette annonce uniquement, non du marché entier
      type: object
      required:
      - listing_id
      - source_url
      - current_price
      - history_status
      - estimate
      - price_history
      - price_volatility
      title: ListingAnalysisOut
    EstimateIn:
      properties:
        make:
          type: string
          maxLength: 50
          minLength: 1
          title: Make
        model:
          type: string
          maxLength: 100
          minLength: 1
          title: Model
        year:
          type: integer
          maximum: 2030.0
          minimum: 1990.0
          title: Year
        mileage:
          type: integer
          maximum: 1000000.0
          minimum: 0.0
          title: Mileage
        energy:
          anyOf:
          - type: string
            maxLength: 50
          - type: 'null'
          title: Energy
        gearbox:
          anyOf:
          - type: string
            maxLength: 50
          - type: 'null'
          title: Gearbox
        motorization:
          anyOf:
          - type: string
            maxLength: 100
          - type: 'null'
          title: Motorization
        finition:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Finition
        asking_price:
          anyOf:
          - type: integer
            minimum: 1.0
          - type: 'null'
          title: Asking Price
          description: Prix demandé, pour situer une offre de négociation
      type: object
      required:
      - make
      - model
      - year
      - mileage
      title: EstimateIn
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ComparableOut:
      properties:
        id:
          type: string
          title: Id
        year:
          type: integer
          title: Year
        mileage:
          type: integer
          title: Mileage
        price:
          type: integer
          title: Price
        source:
          type: string
          title: Source
        source_url:
          type: string
          title: Source Url
        photo_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Photo Url
          description: URL de consultation de la photo ; aucun droit de reproduction n'est concédé
        observed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Observed At
          description: Dernière actualisation connue dans le catalogue
      type: object
      required:
      - id
      - year
      - mileage
      - price
      - source
      - source_url
      title: ComparableOut