API REST / Comparables

Comparables

Trouvez des biens similaires pour estimer la valeur d'un bien immobilier.

GET/v1/comparables10 crédits

Retourne les transactions les plus similaires à un bien cible, classées par proximité et similarité de surface. Utilisez cet endpoint pour construire une estimation de valeur marché : fourchette basse / médiane / haute basée sur des comparables réels.

Paramètres requis

latitude, longitude, type_local, surface_min et surface_max sont tous obligatoires.

Rayon et horizon en zone dense

Commencez à 500 m / 12 mois. Un rayon de 2 km et 36 mois est adapté aux zones rares, pas à une exploration large de centre-ville. Les comparables respectent le rayon et l'horizon explicitement demandés : utilisez une fenêtre plus récente ou découpez votre exploration si nécessaire. Un notice conserve les données obtenues malgré un repli interrompu ; dense_query_timeout ne retourne aucun comparable exploitable et les 10 crédits sont remboursés.

Paramètres

Paramètre	Type	Défaut	Description
latitude*	number	—	Latitude GPS du bien cible (ex. 48.8566)
longitude*	number	—	Longitude GPS du bien cible (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.
type_local*	enum	—	Maison \| Appartement
surface_min*	number	—	Surface minimum en m² (ex. surface cible × 0.8)
surface_max*	number	—	Surface maximum en m² (ex. surface cible × 1.2)
pieces	number	—	Nombre de pièces (tolérance ±1)
radius_m	number	500	Rayon de recherche en mètres (100–2000)
max_age_months	number	18	Ancienneté max des transactions (1–36 mois)
limit	number	10	Nombre maximum de comparables (1–20)
exclude_bulk_sales	boolean	true	Exclure les ventes en lot

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

curl "https://mcp.normi.fr/v1/comparables?latitude=48.8581&longitude=2.3790&type_local=Appartement&surface_min=52&surface_max=78&radius_m=500&max_age_months=12" \
  -H "X-API-Key: normi_votre_token"

Réponse

{
  "comparables": [
    {
      "distance_m": 187,
      "age_days": 63,
      "similarity_score": 0.94,
      "property": {
        "address": "15 RUE DE LA ROQUETTE, 75011, PARIS 11",
        "type": "Appartement", "surface": 63.5, "rooms": 3,
        "price": 598000, "price_per_m2": 9417, "date": "2024-11-15"
      }
    }
  ],
  "valuation_estimate": {
    "price_range": { "low": 513338, "mid": 611845, "high": 715859 },
    "price_per_m2": { "median": 9413, "used_surface": 65 },
    "confidence": "medium",
    "based_on_count": 8,
    "methodology": "Median price/m² of 8 comparable properties within 500m, last 12 months. Interval calibrated on dispersion=15-30% (n=731).",
    "interval": {
      "method": "iqr_p25_p75",
      "coverage_label": "50%",
      "basis": "cohort",
      "cohort": "dispersion=15-30%",
      "cohort_eligible_n": 731,
      "ratio_low": 0.839,
      "ratio_high": 1.17,
      "contract_version": "valuation-comparables-v1",
      "calibration_generated_at": "2026-08-26T07:27:19+00:00"
    },
    "confidence_factors": {
      "comparable_count": 8,
      "average_similarity": 0.58,
      "fallback_used": false,
      "positive_factors": ["comparable_count_medium", "cohort_well_measured"],
      "limiting_factors": []
    }
  },
  "_credits": { "used": 10, "remaining": 75 },
  "query_time_ms": 287
}

Interpréter les résultats

similarity_score : score 0–1 composé de la surface (40 %), distance (30 %), ancienneté (20 %) et pièces (10 %).
valuation_estimate : médiane non pondérée des prix/m² des meilleurs comparables × surface cible. La fourchette (price_range.low/high) est un intervalle interquartile à 50 % calibré sur un backtest de 2 000 ventes DVF masquées — sa largeur dépend du segment — en premier lieu la dispersion des prix/m² des comparables retenus, voir interval.cohort — jamais d'une constante fixe.
confidence_factors détaille les facteurs, positifs et limitants, qui composent le libellé confidence.
Si moins de 3 comparables sont trouvés, valuation_estimate vaut null ; l'API peut d'abord tenter un repli géographique ou administratif.

GET /v1/stats/market & trends

GET /v1/heatmap