Estimate

Estimation automatisée (AVM) d'un bien immobilier à partir de comparables DVF réels.

GET/v1/estimate10 crédits

Retourne une fourchette d'estimation (basse / médiane / haute) calculée à partir des transactions comparables les plus proches. Fournit également le prix au m², un score de confiance et le nombre de comparables utilisés.

Paramètres requis

latitude, longitude et surface sont obligatoires. Le type_local est optionnel et vaut Appartement par défaut.

Même stratégie que les comparables

L'estimation sélectionne d'abord des comparables. Commencez donc à 500 m / 12 mois ; 2 km et jusqu'à 24 mois sont réservés aux zones rares. Le rayon et l'horizon demandés ne sont pas réduits silencieusement. Un notice accompagne une réponse partielle ;dense_query_timeout ne produit pas d'estimation et les crédits sont remboursés.

Paramètres

Paramètre	Type	Défaut	Description
latitude*	number	—	Latitude GPS du bien (ex. 48.8566)
longitude*	number	—	Longitude GPS du bien (ex. 2.3522)
code_postal	string	—	Optionnel. Fallback administratif si les coordonnées GPS donnent trop peu de comparables.
commune	string	—	Optionnel. Fallback commune si les coordonnées GPS donnent trop peu de comparables.
surface*	number	—	Surface en m² (5–5000)
type_local	enum	Appartement	Maison \| Appartement
pieces	number	—	Nombre de pièces (tolérance ±1 sur les comparables)
radius_m	number	500	Rayon de recherche en mètres (100–2000)
max_age_months	number	18	Ancienneté max des transactions (1–24 mois). Défaut 18 mois car DVF est mis à jour semestriellement.

Exemple — estimer un appartement de 65 m² à Paris 11

curl "https://mcp.normi.fr/v1/estimate?latitude=48.8581&longitude=2.3790&surface=65&type_local=Appartement&pieces=3" \
  -H "X-API-Key: normi_votre_token"

Réponse

{
  "estimate": {
    "price_range": {
      "low": 544447,
      "mid": 614500,
      "high": 691312
    },
    "price_per_m2": {
      "median": 9454,
      "used_surface": 65
    },
    "confidence": "high",
    "based_on_count": 11,
    "methodology": "Median price/m² of 11 comparable properties within 500m, last 18 months. Interval calibrated on dispersion=<15% (n=338).",
    "interval": {
      "method": "iqr_p25_p75",
      "coverage_label": "50%",
      "basis": "cohort",
      "cohort": "dispersion=<15%",
      "cohort_eligible_n": 338,
      "ratio_low": 0.886,
      "ratio_high": 1.125,
      "contract_version": "valuation-comparables-v1",
      "calibration_generated_at": "2026-08-26T07:27:19+00:00"
    },
    "confidence_factors": {
      "comparable_count": 11,
      "average_similarity": 0.82,
      "fallback_used": false,
      "positive_factors": ["comparable_count_high", "high_similarity", "cohort_well_measured", "comparables_agree"],
      "limiting_factors": []
    }
  },
  "input": {
    "latitude": 48.8581,
    "longitude": 2.379,
    "surface": 65,
    "type_local": "Appartement"
  },
  "_credits": { "used": 10, "remaining": 85 },
  "query_time_ms": 312
}

Réponse sans comparables suffisants

Si moins de 3 comparables sont trouvés, estimate est null et un message d'aide est retourné. Les 10 crédits sont quand même déduits.

{
  "estimate": null,
  "message": "Insufficient comparable transactions. Try increasing radius_m or max_age_months.",
  "input": { ... },
  "_credits": { "used": 10, "remaining": 75 },
  "query_time_ms": 198
}

Interpréter les résultats

confidence : high, medium ou low — reflète le nombre de comparables et leur similarité moyenne, pas une probabilité calibrée. Le détail traçable est dans confidence_factors, qui signale notamment comparables_agree et comparables_disagree — pourquoi la fourchette est étroite ou large.
price_range.low/high : intervalle interquartile à 50 % (interval.ratio_low/ratio_high), calibré sur des ventes DVF masquées d'un backtest de 2 000 cibles — sa largeur varie selon le segment — d'abord la dispersion des prix/m² des comparables retenus (interval.cohort = dispersion=…), puis leur nombre, le type de bien et la surface — et n'est jamais une constante fixe. Le point central n'est pas affecté par ce routage.
interval.basis vaut cohort quand un segment a assez de données mesurées (≥30 cibles), sinon global — l'intervalle est alors plus large, jamais absent.
price_range.mid : médiane non pondérée des prix/m² des comparables sélectionnés, × surface cible.
Pour les zones denses (Paris, Lyon…), réduire radius_m à 200–300 m améliore la précision.
Utilisez GET /v1/comparables si vous souhaitez accéder aux transactions individuelles utilisées pour le calcul.

GET /v1/heatmap

GET /v1/market-score