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.

Endpoint	Crédits
/v1/transactions	5
/v1/transactions/:id	2
/v1/stats/market	5
/v1/stats/trends	10
/v1/comparables	10
/v1/heatmap	15
/v1/estimate	10
/v1/market-score	10
/v1/portfolio	0–10
/v1/alerts	0–10
/v1/stats/compare	10
/v1/market-activity	10
/v1/property-history	20

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

Plan	Requêtes / minute
Free	60 req/min
Agent	30 req/min
Pro	60 req/min
Enterprise	120 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."
  }
}

HTTP	Signification	Cause fréquente
401	Unauthorized	Clé absente, invalide ou révoquée.
400	Bad Request	Paramètre manquant ou invalide (ex. localisation absente).
402	Payment Required	Crédits insuffisants.
429	Too Many Requests	Limite de débit dépassée.
503	Service Unavailable	Serveur à capacité maximale, réessayez.