---
title: "Estimation affinée par IA"
method: POST
path: "/estimations/affinees"
---

# Estimation affinée par IA

`POST /estimations/affinees`

## Request

- Base URL: `https://pillr.fr/api/v1`
- URL: `https://pillr.fr/api/v1/estimations/affinees`
- Auth: HTTP bearer

La même estimation qu'estimer_bien (même moteur, même sortie), affinée par un modèle de langage à partir de l'état, des qualités, de la description, de l'exposition, des annexes, des équipements et de photos lues sur des liens https publics (JPEG, PNG ou WebP). Rend en plus la liste unique des ajustements, chacun avec sa nature, son pourcentage, son motif et sa source (barème ou IA, chaque ligne IA vérifiée par le serveur), l'état de l'affinage et la lecture des photos. Les photos sont lues le temps de l'appel, jamais écrites ni renvoyées. Une panne de l'IA rend l'estimation déterministe, et le dit. Coût : 30 crédits par appel réussi.

## Request body

- object
  - `adresse` string: Adresse du bien en toutes lettres, numéro et commune compris.
  - `code_postal` string: Code postal, pour départager une adresse homonyme.
  - `insee` string: Code INSEE de la commune, quand l'adresse n'est pas donnée.
  - `type` 'appartement' | 'maison', required
  - `surface` number, required: Surface habitable, en m².
  - `pieces` integer
  - `chambres` integer
  - `etage` integer: Appartement : étage, 0 pour le rez-de-chaussée.
  - `etages_immeuble` integer
  - `ascenseur` boolean
  - `terrain_m2` number: Maison : surface du terrain, en m².
  - `dpe` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G'
  - `annee_construction` integer
  - `prix_demande` integer: Prix demandé ou affiché, en euros.
  - `loyer_pratique` number: Loyer mensuel pratiqué, en euros : remplace le loyer estimé dans le rendement.
  - `etat` 'a_renover' | 'travaux' | 'correct' | 'renove' | 'neuf': État d'entretien du bien.
  - `qualites` string[]: Qualités ou défauts du bien, une courte phrase chacun.
  - `description` string: Description libre du bien.
  - `exposition` 'nord' | 'sud' | 'est' | 'ouest' | 'sud_est' | 'sud_ouest' | 'nord_est' | 'nord_ouest' | 'traversant'
  - `annexes` object
    - `parking` integer
    - `garage` boolean
    - `cave` boolean
    - `balcon_m2` number
    - `terrasse_m2` number
  - `equipements` string[]: Équipements, clés du catalogue de la page /estimation ; une clé inconnue est ignorée.
  - `photos` string[]: Liens https publics vers des photos du bien (JPEG, PNG ou WebP), 12 au plus, de 1.6 Mo chacune au plus. Aucune redirection n'est suivie.

## Response `200`

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

- object
  - `bien` object, required
    - `type` 'appartement' | 'maison', required
    - `surface_m2` number, required
    - `pieces` integer, nullable, required
    - `commune` string, required
    - `code_postal` string, nullable, required
    - `insee` string, nullable, required
    - `origine` 'adresse' | 'commune', required: adresse : faits situés à l'adresse donnée ; commune : faits décrits dans la commune.
  - `valeur` object, required
    - `bas` number, required
    - `valeur` number, required
    - `haut` number, required
    - `prix_m2` number, required
    - `demi_largeur_pct` number, required: Demi-largeur de la fourchette, en % de la valeur.
    - `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.
  - `niveau` object, required
    - `nature` 'mesure' | 'estime', required: mesure : ventes DVF réelles ; estime : modèle Pillr, faute de ventes locales du type.
    - `socle` 'comparables_dvf' | 'iris' | 'commune', required: Socle retenu par la cascade : ventes comparables, quartier ou commune.
    - `libelle` string, required
    - `ventes` integer, required
    - `rayon_m` number, nullable, required
    - `millesime` integer, nullable, required
    - `prix_m2_socle` number, required: Prix au m² du socle, avant les ajustements du bien.
  - `fiabilite` 'elevee' | 'correcte' | 'limitee', required
  - `comparables` object, required
    - `n` integer, required
    - `prix_m2_median` number, nullable, required
    - `millesimes` integer[], required
    - `ventes` object[], required: Ventes DVF retenues, avec leur adresse DVF quand elle est retrouvée et leurs coordonnées. Vide sans adresse précise ou faute de ventes assez proches.
      - `date` string, required
      - `type` 'appartement' | 'maison', required
      - `surface_m2` number, required
      - `prix` number, required
      - `prix_m2` number, required
      - `distance_m` number, nullable, required: Distance au bien, arrondie à 50 m.
      - `millesime` integer, required
      - `adresse` string, nullable, required: Adresse DVF de la vente (numéro et voie), relue au lac par la commune, la date et le prix ; null si la vente est introuvable, ambiguë ou sans numéro.
      - `code_postal` string, nullable, required
      - `id_mutation` string, nullable, required: Identifiant DVF de la mutation, quand l'adresse a été retrouvée.
      - `lat` number, nullable, required: Latitude DVF de la vente (open data).
      - `lon` number, nullable, required: Longitude DVF de la vente (open data).
  - `loyer` object, nullable, required
    - `mensuel` number, required
    - `bas` number, nullable, required
    - `haut` number, nullable, required
    - `nature` 'observe_commune' | 'predit_maille', required: observe_commune : loyer d'annonce observé dans la commune ; predit_maille : prédit à la maille de la Carte des loyers.
    - `charges_comprises` true, required: Loyer d'annonce de la Carte des loyers, charges comprises.
    - `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.
  - `rendement` object, nullable, required: null sans loyer estimé ni loyer pratiqué.
    - `sur` 'prix_demande' | 'valeur_estimee', required: Prix sur lequel les rendements sont calculés.
    - `prix` number, required
    - `loyer` 'pratique' | 'estime', required: Loyer retenu : celui donné par l'appelant, ou le loyer estimé.
    - `loyer_mensuel` number, required
    - `brut_pct` number, required: 12 fois le loyer mensuel, divisé par le prix, en %.
    - `frais_notaire` number, required: Frais d'acquisition retenus : 8 % du prix, en euros.
    - `net_hors_travaux_pct` number, required: 85 % de 12 fois le loyer mensuel, divisés par le prix augmenté des frais, en %. Aucun budget de travaux n'est compté : cette opération n'en estime pas.
  - `prix_demande` object, nullable, required: Le prix demandé situé face au marché ; null sans prix demandé.
    - `prix` number, required
    - `prix_m2` number, required
    - `ecart_pct` number, required: Écart du prix demandé à la valeur estimée, en % (positif : plus cher).
    - `position` 'sous_la_fourchette' | 'dans_la_fourchette' | 'au_dessus_de_la_fourchette', required
    - `annonces_en_vente` object, nullable, required: Annonces comparables en vente dans la commune (prix affichés) ; null quand elles sont trop peu nombreuses.
      - `n` integer, required
      - `prix_m2_median` number, required
      - `part_moins_cheres_pct` number, required
    - `baisses` object, nullable, required: Annonces comparables du secteur dont le prix a baissé, sans remontée ; null quand elles sont trop peu nombreuses.
      - `biens` integer, required
      - `annonces_suivies` integer, required
      - `baisse_mediane_pct` number, required
      - `prix_m2_median_apres_baisse` number, required
      - `fenetre_jours` integer, required
    - `retraits` object, nullable, required: Annonces comparables retirées de la vente (vendues, expirées ou retirées, sans distinction possible) ; null quand elles sont trop peu nombreuses.
      - `biens` integer, required
      - `dernier_prix_m2_median` number, required
      - `fenetre_jours` integer, required
  - `dpe` object, nullable, required: null sans étiquette DPE donnée.
    - `classe` 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G', required
    - `interdiction_location` string, nullable, required: Premier jour où la location d'un logement de cette classe est interdite (AAAA-MM-JJ), selon le calendrier de la loi Climat et résilience en métropole (G 2025, F 2028, E 2034). null : classe sans échéance, DPE absent, ou adresse hors de la métropole (le calendrier des outre-mer n'est pas servi).
    - `mois_restants` integer, nullable, required: Mois pleins avant l'échéance ; 0 quand l'interdiction est déjà en vigueur ; null sans échéance.
    - `sortie` object, nullable, required: Coût de sortie d'une passoire (classe E, F ou G) vers D, C ou B, mesuré sur les audits énergétiques réglementaires de l'ADEME pour des logements comparables. null hors des classes E à G, pour un type de logement sans comparable, ou hors de la métropole.
      - `classe_depart` 'E' | 'F' | 'G', required
      - `cibles` object[], required
        - `vers` 'D' | 'C' | 'B', required: Classe visée.
        - `n_audits` integer, required: Nombre d'audits comparables de la cellule retenue.
        - `euros` object, required: Coût des travaux chiffré par les audits comparables, sur leurs propres surfaces, en euros arrondis à la centaine.
          - `mediane` number, required
          - `p25` number, required
          - `p75` number, required
        - `eur_m2` object, nullable, required: Le même coût rapporté à la surface habitable, en euros par m² ; null s'il y a trop peu d'audits avec surface.
          - `mediane` number, required
          - `p25` number, required
          - `p75` number, required
        - `surface_mediane_m2` number, nullable, required: Surface habitable médiane des logements audités.
        - `pour_la_surface` object, nullable, required: Le coût au m² des audits appliqué à la surface du bien, quand elle est connue : le chiffre à citer.
          - `surface_m2` number, required
          - `mediane` number, required
          - `p25` number, required
          - `p75` number, required
        - `part_au_dela` number, nullable, required: Part des audits (0 à 1) dont l'étape chiffrée atteint déjà la classe suivante : le chiffrage dépasse alors la cible.
        - `perimetre` string, required: Les audits comparables, en clair (type de logement, zone climatique, période de construction).
        - `niveau` 'complet' | 'sans_periode' | 'sans_zone' | 'national', required: Finesse de la cellule retenue, de la plus fine (type, zone climatique et période) à la plus large (type seul, France métropolitaine).
      - `lecture` string, required: Ce que mesure le chiffre : une estimation d'auditeur, pas un devis.
      - `source` string, required
  - `erreur` string, required: L'erreur de la méthode, telle que le moteur la publie.
  - `limites` string[], required
  - `mention` string, required
  - `sources` string[], required
  - `calcule_le` string, required
  - `ajustements` object[], required: La liste unique des ajustements appliqués, une ligne par nature.
    - `nature` string, required: Nature de l'ajustement (surface, etage, dpe, etat_general, prestations...).
    - `libelle` string, required
    - `pct` number, required: Points de pourcentage appliqués au prix de référence du secteur.
    - `motif` string, nullable, required
    - `source` 'bareme' | 'ia', required: bareme : repère calculé sur nos données ; ia : lecture de la description ou des photos, vérifiée par le serveur.
  - `affinage` object, required
    - `applique` boolean, required
    - `modele` string, nullable, required: Modèle de langage qui a relu le dossier, quand l'affinage a tourné.
    - `raison` string, required
  - `vision` object, nullable, required: La lecture des photos ; null sans photo.
    - `disponible` boolean, required
    - `photos_recues` integer, required
    - `photos_analysees` integer, required
    - `equipements` string[], required: Équipements reconnus sur les photos (catalogue de la page /estimation).
    - `constats` string[], required: Constats factuels tirés des photos, sans prix ni pourcentage.
    - `raison_indisponible` string, nullable, 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

- `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)