REST API — Vue d'ensemble

Accédez aux données DVF depuis n'importe quel langage avec une API REST standard.

URL de base

https://mcp.normi.fr/v1

Tous les endpoints retournent du JSON. HTTPS uniquement.

Authentification

Passez votre clé API dans le header X-API-Key. Générez une clé depuis le tableau de bord → Tokens.

curl "https://mcp.normi.fr/v1/stats/market?code_postal=75001" \
  -H "X-API-Key: normi_votre_token"
Header alternatif
Le header Authorization: Bearer VOTRE_TOKEN est également accepté pour la compatibilité MCP.

Format de réponse

Toutes les réponses incluent les champs _credits et query_time_ms :

{
  "total_transactions": 563,
  "median_price": 527000,
  "median_price_m2": 13850,
  "avg_price": 612000,
  "avg_price_m2": 15200,
  "_credits": { "used": 5, "remaining": 95 },
  "query_time_ms": 1025
}

Le champ note dans _credits apparaît uniquement quand il reste moins de 20 crédits.

Crédits

Chaque requête déduit des crédits selon sa complexité. En cas de crédits insuffisants, l'API retourne HTTP 402 sans exécuter la requête.

EndpointCrédits
/v1/transactions5
/v1/transactions/:id2
/v1/stats/market5
/v1/stats/trends10
/v1/comparables10
/v1/heatmap15
/v1/estimate10
/v1/market-score10
/v1/portfolio0–10
/v1/alerts0–10
/v1/stats/compare10
/v1/market-activity10
/v1/property-history20
/v1/transactions/:id/dpe2
/v1/dpe/stats10
/v1/stats/dpe-premium10
/v1/dpe/prix-par-classe10
/v1/dpe/passoires-thermiques10
/v1/dpe/evolution-prime-verte10
/v1/transactions/:id/bdnb2
/v1/bdnb/age-stats10
/v1/bdnb/renovation-score10
/v1/bdnb/stats5

Achetez des crédits ou passez à un abonnement depuis la page Tarifs.

Pagination

GET /v1/transactions supporte la pagination par offset. Paramètres : limit (max 200, défaut 50) et offset. La réponse inclut next_cursor (null si dernière page).

# Page 1
GET /v1/transactions?code_postal=75001&limit=50&offset=0
→ { ..., "next_cursor": 50, "pagination": { "total": 563, "has_more": true } }

# Page 2
GET /v1/transactions?code_postal=75001&limit=50&offset=50
→ { ..., "next_cursor": 100 }

Limites de débit

PlanRequêtes / minute
Free60 req/min
Agent30 req/min
Pro60 req/min
Enterprise120 req/min

Au-delà de la limite, l'API retourne HTTP 429. Le header Retry-After indique le délai d'attente.

Format d'erreur

Toutes les erreurs retournent un objet JSON avec un code machine et un message lisible :

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits. Required: 5, available: 3."
  }
}
HTTPSignification
401Unauthorized
400Bad Request
402Payment Required
429Too Many Requests
503Service Unavailable

Endpoints

GET
/v1/transactions5 crédits

Rechercher des transactions DVF avec filtres géographiques, type, prix, surface et date.

GET
/v1/transactions/:id2 crédits

Détail d'une transaction par son identifiant.

GET
/v1/stats/market5 crédits

Statistiques agrégées : médiane, moyenne, prix/m², volume pour une zone.

GET
/v1/stats/trends10 crédits

Évolution des prix dans le temps (mensuel, trimestriel, annuel).

GET
/v1/comparables10 crédits

Biens similaires autour d'un point GPS pour estimation de valeur.

GET
/v1/heatmap15 crédits

Prix agrégés par code postal ou commune pour cartographier un département.

GET
/v1/estimate10 crédits

Estimation automatisée (AVM) : fourchette basse/médiane/haute à partir de comparables DVF.

GET
/v1/market-score10 crédits

Score de santé du marché (0–100) pour un code postal, une commune ou un département.

CRUD
/v1/portfolio10 crédits

Gérez un portefeuille de biens avec estimations automatiques (POST/GET/PUT/DELETE).

CRUD
/v1/alerts

Alertes webhook sur nouvelles transactions DVF — Pro/Enterprise uniquement (POST/GET/PUT/DELETE).

GET
/v1/stats/compare10 crédits

Comparer 2 à 5 zones géographiques côte à côte : prix, volume, évolution.

GET
/v1/market-activity10 crédits

Volume mensuel et saisonnalité du marché immobilier sur une zone donnée.

GET
/v1/property-history20 crédits

Historique complet des transactions pour une adresse ou une parcelle cadastrale.

GET
/v1/transactions/:id/dpe2 crédits

Diagnostic DPE (classe A–G, énergie, GES) pour une transaction DVF précise.

GET
/v1/dpe/stats10 crédits

Distribution des classes énergétiques (A–G) et médianes de consommation pour une zone.

GET
/v1/stats/dpe-premium10 crédits

Prime de prix par classe DPE — croisement DVF×DPE sur références cadastrales.

GET
/v1/dpe/prix-par-classe10 crédits

Médiane prix/m² par classe DPE avec taux de couverture et prime verte vs classe D.

GET
/v1/dpe/passoires-thermiques10 crédits

Part et tendance annuelle des passoires thermiques F/G depuis 2022.

GET
/v1/dpe/evolution-prime-verte10 crédits

Série temporelle annuelle du prix/m² A+B vs F+G — écart croissant entre classes.

GET
/v1/transactions/:id/bdnb2 crédits

Caractéristiques BDNB du bâtiment le plus proche d'une transaction DVF (année, matériaux, usage, étages).

GET
/v1/bdnb/age-stats10 crédits

Prix médian/m² DVF par tranche de construction (<1919, 1919–1945, 1946–1970, 1971–1990, 1991–2005, 2006+).

GET
/v1/bdnb/renovation-score10 crédits

Score de potentiel de rénovation (0–100) : anciens bâtiments sous-valorisés par rapport à la médiane de zone.

GET
/v1/bdnb/stats5 crédits

Stock de bâtiments par commune ou département : répartition par tranche, usage et nombre de logements.

Précédent
Première requête REST
Suivant
GET /v1/transactions