Documentation de l'API DVF

Référence complète de l'API DVF pour accéder aux données de transactions immobilières en France. Tous les endpoints, paramètres et exemples de réponses.

URL de base

https://immoapi.app

Authentification

Chaque requête doit inclure votre clé API, soit via le header Authorization: Bearer, soit via le header x-api-key (les deux sont acceptés).

Authorization: Bearer YOUR_API_KEY

Obtenez votre clé API en créant un compte sur Immo API. La clé est disponible immédiatement après inscription dans votre tableau de bord.

Limites de requêtes

Les limites varient selon votre plan :

Plan	Limite	Fenêtre
Starter	1 000 requêtes	Par jour
Pro	Illimité	-

Les headers de réponse incluent X-RateLimit-Remaining et X-RateLimit-Reset pour suivre votre consommation.

GET

/api/mutations

Recherchez des transactions immobilières (mutations) dans la base DVF. Filtrez par commune, département, type de bien, fourchette de prix et période.

Paramètres

Paramètre	Type	Statut	Description
`commune`	string	optionnel	Nom de la commune — recherche souple, insensible à la casse, gère les arrondissements (« Paris » couvre « Paris 1er Arrondissement »…)
`code_postal`	string	optionnel	Code postal (ex : 75001, 69001)
`type_local`	string	optionnel	Type de bien : Appartement, Maison, Local industriel. commercial ou assimilé, Dépendance
`annee`	integer	optionnel	Année de la transaction (ex : 2024)
`prix_min`	integer	optionnel	Valeur foncière minimale en euros
`prix_max`	integer	optionnel	Valeur foncière maximale en euros
`limit`	integer	optionnel	Nombre de résultats (défaut : 100, max : 1000)
`offset`	integer	optionnel	Décalage de pagination (défaut : 0)

Exemple de requête

curl "https://immoapi.app/api/mutations?commune=Paris&type_local=Appartement&annee=2024&prix_min=200000&prix_max=600000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemple de réponse

{
  "count": 100,
  "limit": 100,
  "offset": 0,
  "data": [
    {
      "id_mutation": "2024-1292937",
      "date_mutation": "2024-03-15",
      "nature_mutation": "Vente",
      "valeur_fonciere": "485000.00",
      "adresse_nom_voie": "RUE DE RIVOLI",
      "code_postal": "75001",
      "code_commune": "75101",
      "commune": "Paris 1er Arrondissement",
      "code_departement": "75",
      "type_local": "Appartement",
      "surface_reelle_bati": 65,
      "nombre_pieces_principales": 3,
      "longitude": "2.3488",
      "latitude": "48.8566"
    }
  ]
}

GET

/api/mutations/nearby

Recherchez les transactions immobilières à proximité d'un point géographique (latitude / longitude). Idéal pour trouver des comparables dans un quartier.

Paramètres

Paramètre	Type	Statut	Description
`lat`	float	optionnel	Latitude du point central. Requis si code_postal est absent.
`lng`	float	optionnel	Longitude du point central. Requis si code_postal est absent.
`code_postal`	string	optionnel	Code postal utilisé pour calculer un centre automatique (alternative à lat/lng)
`radius`	float	optionnel	Rayon de recherche en kilomètres (défaut : 5, min : 0.1, max : 50)
`type_local`	string	optionnel	Type de bien : Appartement, Maison, Local industriel, Dépendance
`annee`	integer	optionnel	Année de la transaction
`limit`	integer	optionnel	Nombre de résultats (défaut : 20, max : 100)

Exemple de requête

curl "https://immoapi.app/api/mutations/nearby?lat=48.8566&lng=2.3522&radius=1&type_local=Appartement" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemple de réponse

{
  "count": 18,
  "radius_km": 1,
  "center": {
    "lat": 48.8566,
    "lng": 2.3522
  },
  "data": [
    {
      "date_mutation": "2024-02-20",
      "valeur_fonciere": "520000.00",
      "commune": "Paris 1er Arrondissement",
      "code_postal": "75001",
      "type_local": "Appartement",
      "surface_reelle_bati": 55,
      "longitude": "2.3470",
      "latitude": "48.8580",
      "distance_km": 0.12
    }
  ]
}

GET

/api/stats

Obtenez des statistiques agrégées sur les transactions immobilières : prix médian et moyen au m², volume de transactions, évolution annuelle. Filtrez par zone géographique et période.

Paramètres

Paramètre	Type	Statut	Description
`commune`	string	optionnel	Nom de la commune (recherche souple, gère les arrondissements)
`code_postal`	string	optionnel	Code postal à analyser (ex : 75001)

Les statistiques sont calculées sur les ventes uniquement, dédupliquées par mutation. Le prix au m² médian est calculé sur les ventes résidentielles mono-lot. Privilégiez la médiane et le prix/m² médian (plus robustes que la moyenne).

Exemple de requête

curl "https://immoapi.app/api/stats?code_postal=75001" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemple de réponse

{
  "total_mutations": 2222,
  "prix_moyen": 1779393,
  "prix_median": 525000,
  "prix_p25": 256749,
  "prix_p75": 1112375,
  "prix_min": 1500,
  "prix_max": 171972528,
  "prix_m2_median": 12727,
  "surface_moyenne": 57
}

MCP

/api/mcp

Immo API expose un serveur MCP pour connecter directement vos agents IA aux données DVF. Le transport est HTTP JSON-RPC et utilise la même clé API que les endpoints REST.

Installation Claude Code

claude mcp add --transport http immoapi \
  https://immoapi.app/api/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

Le serveur est stateless et compatible avec les clients MCP qui supportent le transport Streamable HTTP, dont Claude Code, Cursor, VS Code et les bridges de type mcp-remote.

Test JSON-RPC

curl -X POST "https://immoapi.app/api/mcp" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Outils disponibles

Tool	Usage agent IA
`search_mutations`	Rechercher des transactions DVF par commune, code postal, année, type de bien et prix.
`search_nearby_mutations`	Trouver des comparables autour de coordonnées GPS ou d'un code postal.
`get_market_stats`	Calculer les agrégats de marché nécessaires aux analyses et estimations.

Les appels MCP ont un rate limit dédié de 60 requêtes par minute par clé API, avec headers X-RateLimit-Remaining et X-RateLimit-Reset.

Documentation MCP complète : consultez la référence détaillée du serveur MCP pour les schémas de paramètres, les exemples JSON-RPC complets, les instructions d'installation Cursor/VS Code/Windsurf et les cas d'usage agents IA.

Codes d'erreur

Code HTTP	Signification	Description
`400`	Bad Request	Paramètres invalides ou manquants
`401`	Unauthorized	Clé API manquante ou invalide
`429`	Too Many Requests	Limite de requêtes atteinte
`500`	Internal Server Error	Erreur serveur, réessayez plus tard

{
  "error": {
    "code": 401,
    "message": "Clé API invalide ou manquante",
    "detail": "Vérifiez que le header Authorization contient un Bearer token valide."
  }
}

À propos de la documentation Immo API

Cette documentation couvre l'ensemble des endpoints de l'API DVF. L'API permet d'accéder aux données officielles de transactions immobilières en France issues des Demandes de Valeurs Foncières (DVF). Que vous construisiez un outil d'estimation, un tableau de bord analytique ou une application immobilière, cette documentation vous guide pas à pas dans l'intégration de l'API de transactions immobilières.