API REST / Transactions

Transactions

Recherchez et récupérez des transactions immobilières DVF.

GET/v1/transactions5 crédits

Recherche des transactions DVF avec filtres.

Filtre de localisation requis : code_postal, commune, code_departement, ou latitude + longitude.

Paramètres

Paramètre	Type	Défaut	Description
code_postal	string	—	Code postal (ex. '75001')
commune	string	—	Nom de la commune (ex. 'LYON', 'PARIS 03')
code_departement	string	—	Code département (ex. '69')
latitude	number	—	Latitude (nécessite aussi longitude)
longitude	number	—	Longitude (nécessite aussi latitude)
radius_m	number	500	Rayon en mètres pour recherche GPS (max 2000). Au-delà de 1000 m, sans date explicite, la fenêtre est limitée à 12 mois avec notice.
type_local	enum	—	Maison \| Appartement \| Terrain \| Local commercial \| Dépendance \| Local industriel
prix_min	number	—	Prix minimum en euros
prix_max	number	—	Prix maximum en euros
surface_min	number	—	Surface minimum en m²
surface_max	number	—	Surface maximum en m²
date_debut	string	—	Date de début (YYYY-MM-DD)
date_fin	string	—	Date de fin (YYYY-MM-DD)
exclude_bulk_sales	boolean	true	Exclure les ventes en lot
exclude_vefa	boolean	true	Exclure les ventes en VEFA (neuf)
limit	number	50	Nombre de résultats (max 200)
offset	number	0	Décalage pour la pagination
summary_only	boolean	false	Retourner un résumé et 3 exemples. Le résumé couvre toutes les ventes correspondantes (même calcul que /v1/stats/market) ; avec prix_, surface_ ou pieces_min, il ne décrit que la page (summary.basis = sample)

exclude_outliers est obsolète

Les prix aberrants sont retirés à l'ingestion : aucune transaction publiée n'en est un. Le paramètre exclude_outliers n'a donc aucun effet sur cet endpoint. Il reste accepté et ignoré, et la réponse contient alors un champ notice qui le signale. Voir qualité des données.

Exemples

curl "https://mcp.normi.fr/v1/transactions?code_postal=75001&type_local=Appartement&limit=5" \
  -H "X-API-Key: normi_votre_token"

Réponse

{
  "transactions": [
    {
      "id": 12345678,
      "date_mutation": "2025-06-30",
      "valeur_fonciere": 1780000,
      "code_postal": "75001",
      "commune": "PARIS 01",
      "type_local": "Appartement",
      "surface_reelle_bati": 142,
      "surface_carrez_lot1": 104.83,
      "nombre_pieces_principales": 3,
      "prix_m2": 12535,
      "latitude": 48.8641,
      "longitude": 2.3381
    }
  ],
  "pagination": { "total": 563, "limit": 5, "offset": 0, "has_more": true },
  "next_cursor": 5,
  "_credits": { "used": 5, "remaining": 95 },
  "query_time_ms": 312
}

GET/v1/transactions/:id2 crédits

Retourne le détail d'une transaction par son identifiant numérique DVF. HTTP 404 si introuvable (crédits remboursés).

Exemple

curl "https://mcp.normi.fr/v1/transactions/12345678" \
  -H "X-API-Key: normi_votre_token"

Gotchas à connaître

Paris est stocké par arrondissement : PARIS 01, PARIS 02… Utilisez commune=PARIS pour tous les arrondissements simultanément.
Grands codes postaux (75015–75020) : recommandez date_debut pour éviter les timeouts.
Transactions par rayon > 1000m : sans date_debut, limitées automatiquement aux 12 derniers mois et signalées par notice. Pour une zone dense, commencez à 500 m / 12 mois puis découpez vos fenêtres de date.

GET /v1/locations/resolve

GET /v1/stats/market & trends