CarHunt Marché API

openapi: 3.2.0
info:
  title: CarHunt Pro Marché 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: Marché
paths:
  /v1/listings/{listing_id}/market:
    get:
      tags:
      - Marché
      summary: Position marché d'une annonce
      description: Médiane de prix du segment comparable + écart de l'annonce vs marché.
      operationId: listing_market_v1_listings__listing_id__market_get
      parameters:
      - name: listing_id
        in: path
        required: true
        schema:
          type: string
          title: Listing Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketOut'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    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
    MarketOut:
      properties:
        listing_id:
          type: string
          title: Listing Id
        price:
          anyOf:
          - type: integer
          - type: 'null'
          title: Price
        market_median:
          anyOf:
          - type: integer
          - type: 'null'
          title: Market Median
          description: Prix médian du segment (même modèle, ±1 an, tranche de km)
        comparable_count:
          type: integer
          title: Comparable Count
          description: Nombre d'annonces comparables utilisées
          default: 0
        savings:
          anyOf:
          - type: integer
          - type: 'null'
          title: Savings
          description: Écart € vs médiane (positif = sous la cote)
        undercut_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Undercut Pct
          description: Écart % vs médiane
      type: object
      required:
      - listing_id
      title: MarketOut