---
title: "Écart au marché, anomalies et ventes du rayon"
method: GET
path: "/annonces/{id}/ecart-marche"
---

# Écart au marché, anomalies et ventes du rayon

`GET /annonces/{id}/ecart-marche`

## Request

- Base URL: `https://pillr.fr/api/v1`
- URL: `https://pillr.fr/api/v1/annonces/{id}/ecart-marche`
- Auth: HTTP bearer

Écart du prix au m² d'une annonce analysée au prix de référence Pillr de sa commune (le chiffre de la fiche, calculé par le même module canonique), avec le signal du modèle prédictif, les anomalies annonce contre marché du moteur de règles, les données de l'analyse (travaux, rendements, loyer, score, profil), les cibles et leviers de négociation, et toutes les ventes DVF du rayon une par une, reconstituées à la mutation entière, avec leurs agrégats par type et par année. Aucun seuil ne masque : chaque agrégat porte son nombre de ventes, chaque vente atypique son drapeau. Rien n'est débité si l'annonce est absente. Coût : 3 crédits par appel réussi.

## Path parameters

- `id` string, required: Identifiant de l'annonce : lbc:<numéro>, bienici:<identifiant>, seloger:<numéro> ou identifiant Pillr.

## Query parameters

- `rayon_m` integer: Rayon des ventes DVF autour de l'annonce, en mètres, de 50 à 1 000 (défaut 300).

## Response `200`

Réponse servie et débitée (sauf réponse identique déjà servie dans les 24 h).

- object
  - `id` string, required
  - `id_portail` string, nullable, required
  - `type_vendeur` 'pro' | 'particulier' | 'inconnu', required: Statut du vendeur : pro (professionnel nommé), particulier, ou inconnu quand le portail ne le dit pas. Une annonce qui n'est pas celle d'un professionnel perd les téléphones et les emails de ses textes.
  - `prix_m2_annonce` number, nullable, required
  - `prix_m2_marche` number, nullable, required: Prix de référence Pillr de la commune pour ce type de bien : le chiffre de la fiche.
  - `ecart_pct` number, nullable, required: Écart du prix au m² de l'annonce au prix de référence, en % (positif : plus cher). null quand la référence n'est pas mesurée sur des ventes.
  - `verdict` 'tres_sous_cote' | 'sous_cote' | 'au_marche' | 'sur_cote' | 'tres_sur_cote' | 'inconnu', required
  - `signal_ml` string, nullable, required: Signal du modèle prédictif départemental (un signal, jamais la valeur du marché).
  - `reference` object, required
    - `commune` string, nullable, required
    - `code_insee` string, nullable, required
    - `code_postal` string, nullable, required
    - `provenance` 'dvf' | 'estimation', nullable, required: dvf : médiane de ventes notariées ; estimation : modèle Pillr, faute de ventes locales du type.
    - `qualite` object, required: Ce qui permet de juger la valeur : nombre, provenance, incertitude, drapeaux, date et source.
      - `n` integer, nullable, required: Nombre d'observations derrière la valeur ; null si sans objet.
      - `provenance` 'mesure' | 'estime', nullable, required: mesure : observé sur la donnée ; estime : modèle, barème ou imputation ; null : sans objet.
      - `incertitude` object, nullable, required: Incertitude de la valeur : fourchette et demi-largeur.
        - `demi_largeur_pct` number, nullable, required: Demi-largeur de la fourchette, en % de la valeur.
        - `bas` number, nullable, required
        - `haut` number, nullable, required
      - `drapeaux` string[], required: Ce qui doit faire lire la valeur avec prudence ; vide si rien.
      - `methode` string, nullable, required: Méthode de calcul ou de rattachement, en clair.
      - `donnees_du` string, nullable, required: Date de la donnée (AAAA-MM-JJ ou horodatage ISO 8601).
      - `source` string, required: Source publique ou moteur Pillr, en clair.
  - `anomalies` object[], required
    - `type` string, required
    - `severite` string, required
    - `message` string, required
  - `donnees_annonce` object, required
    - `travaux_statut` string, nullable, required
    - `travaux_min` number, nullable, required
    - `travaux_max` number, nullable, required
    - `rendement_brut` number, nullable, required
    - `rendement_net` number, nullable, required
    - `loyer` number, nullable, required
    - `loyer_source` string, nullable, required
    - `score` number, nullable, required
    - `profil` string, nullable, required
  - `negociation` object, required
    - `cible_min` number, nullable, required
    - `cible_max` number, nullable, required
    - `leviers` string[], required
  - `ventes_rayon` object, required
    - `rayon_m` integer, required
    - `n` integer, required: Ventes typiques du type de l'annonce dans le rayon, toutes années.
    - `mediane_m2` number, nullable, required
    - `q1` number, nullable, required
    - `q3` number, nullable, required
    - `min` number, nullable, required
    - `max` number, nullable, required
    - `millesimes` string, nullable, required
    - `agregats` object[], required
      - `type_bien` 'appartement' | 'maison', required
      - `periode` string, required
      - `nb_ventes` integer, required
      - `prix_m2_median` number, nullable, required
      - `prix_m2_q1` number, nullable, required
      - `prix_m2_q3` number, nullable, required
      - `prix_m2_min` number, nullable, required
      - `prix_m2_max` number, nullable, required
      - `surface_mediane_m2` number, nullable, required
      - `derniere_vente_le` string, nullable, required
      - `nb_prix_atypiques` integer, required: Ventes du groupe écartées de l'agrégat pour prix atypique (listées une par une).
    - `par_annee` object[], required
      - `type_bien` 'appartement' | 'maison', required
      - `periode` string, required
      - `nb_ventes` integer, required
      - `prix_m2_median` number, nullable, required
      - `prix_m2_q1` number, nullable, required
      - `prix_m2_q3` number, nullable, required
      - `prix_m2_min` number, nullable, required
      - `prix_m2_max` number, nullable, required
      - `surface_mediane_m2` number, nullable, required
      - `derniere_vente_le` string, nullable, required
      - `nb_prix_atypiques` integer, required: Ventes du groupe écartées de l'agrégat pour prix atypique (listées une par une).
    - `ventes` object[], required: Toutes les ventes du rayon, une par une, les plus proches d'abord, chacune avec son drapeau prix_atypique.
      - `date` string, required
      - `adresse` string, nullable, required: Numéro et voie tels que DVF les écrit ; null sans numéro.
      - `type_bien` 'appartement' | 'maison', required
      - `surface_m2` number, required
      - `prix` number, nullable, required: Valeur foncière de la mutation entière.
      - `prix_m2` number, required
      - `distance_m` number, nullable, required
      - `id_mutation` string, nullable, required
      - `prix_atypique` boolean, required
      - `motif_atypique` string, nullable, required
    - `note` string, nullable, required
    - `qualite` object, required: Ce qui permet de juger la valeur : nombre, provenance, incertitude, drapeaux, date et source.
      - `n` integer, nullable, required: Nombre d'observations derrière la valeur ; null si sans objet.
      - `provenance` 'mesure' | 'estime', nullable, required: mesure : observé sur la donnée ; estime : modèle, barème ou imputation ; null : sans objet.
      - `incertitude` object, nullable, required: Incertitude de la valeur : fourchette et demi-largeur.
        - `demi_largeur_pct` number, nullable, required: Demi-largeur de la fourchette, en % de la valeur.
        - `bas` number, nullable, required
        - `haut` number, nullable, required
      - `drapeaux` string[], required: Ce qui doit faire lire la valeur avec prudence ; vide si rien.
      - `methode` string, nullable, required: Méthode de calcul ou de rattachement, en clair.
      - `donnees_du` string, nullable, required: Date de la donnée (AAAA-MM-JJ ou horodatage ISO 8601).
      - `source` string, required: Source publique ou moteur Pillr, en clair.
  - `calcule_le` string, required
  - `credits` object, required: Crédits débités par cet appel (réservés, pour une tâche en cours), et crédits encore utilisables ce mois avant la coupure : crédits offerts, crédits inclus du mois et crédits facturables sous le plafond de dépense (null si inconnus ou en bac à sable).
    - `debites` integer, required
    - `restants` integer, nullable, required

## Other responses

- `304`: Non modifiée depuis l'ETag fourni : rien n'est débité.
- `400`: Paramètres invalides
- `401`: Clé d'API absente
- `402`: Crédits insuffisants ; Carte requise ; Plafond mensuel de dépense atteint
- `403`: Portée insuffisante
- `404`: Ressource absente : rien n'est débité
- `429`: Trop de requêtes par minute
- `500`: Erreur interne
- `503`: API indisponible ; Donnée momentanément indisponible

---

[API](https://skmtc.dev/pillr/apis/api-pillr.md) · [All operations](https://skmtc.dev/pillr/apis/api-pillr/llms.txt) · [OpenAPI document](https://skmtc.dev/pillr/apis/api-pillr/revisions/218b2866bd6c?raw)