Match DVF à un bien (V2 stable) - API de données immobilières

À quoi ça sert

POST /v2/protected/opendata/dvf/match recherche, parmi les transactions DVF (Demandes de Valeurs Foncières), celles qui ressemblent le plus à un bien que vous connaissez déjà. Le résultat est une liste de candidats classés par similarité décroissante. Là où la recherche DVF renvoie des transactions paginées sans ordre de pertinence, le Match attribue à chaque candidat un score et un niveau de confidence pour vous dire à quel point il correspond au bien cible. Le payload combine deux mécanismes distincts :

filters (pré-filtre dur) — exclut les transactions qui ne respectent pas le critère. Un candidat hors du département, hors de la bande de surface ou hors de la zone géographique n’apparaît jamais dans la réponse.
scoringTargets (ancres douces) — n’exclut rien. Ces ancres influencent uniquement le classement : un candidat proche du prix cible, avec le même nombre de pièces ou la même nature de transaction, remonte dans la liste.

La réponse contient pour chaque entrée :

score — similarité normalisée de 0 à 100.
confidence — HIGH, MEDIUM, LOW ou REJECT.
dvf — la transaction DVF correspondante (champs essentiels).

Le bloc meta.ambiguous vaut true lorsque les deux premiers résultats ont des scores proches (écart ≤ 5 points) : c’est un signal qu’aucun candidat ne se détache nettement et qu’une vérification manuelle peut être utile.

Payload

Champ	Type	Obligatoire	Sens
`filters`	objet	Non	Pré-filtre dur. Tout candidat ne respectant pas un filtre est exclu de la réponse.
`filters.codeDepartement`	string	Non	Code du département (2-3 caractères, ex : `75`, `2A`, `974`).
`filters.inseeCode`	string	Non	Code INSEE de la commune (5 caractères).
`filters.postalCode`	string	Non	Code postal (5 chiffres).
`filters.mutationId`	string	Non	Identifiant unique d’une mutation DVF. Permet un lookup exact d’une transaction connue.
`filters.propertyType`	enum	Non	Type de bien : `Appartement`, `Maison`, `Autre`, `Terrain`, `Tertiaire`, `Dépendance`, `Volume`.
`filters.surface`	objet `{ min, max }`	Non	Bande de surface habitable en m².
`filters.transactionDate`	objet `{ from, to }`	Non	Fenêtre de dates de transaction (format `YYYY-MM-DD`).
`filters.location`	objet `{ lat, lon, distance }`	Non	Zone géographique. `distance` au format `10km`, `500m`, etc.
`size`	integer	Non	Nombre de candidats retournés. Entre `1` et `20`, défaut `5`.
`scoringTargets`	objet	Non	Ancres de scoring. Influencent le classement sans exclure de candidats.
`scoringTargets.price`	number	Non	Prix cible en euros (décroissance gaussienne : plus le candidat est proche, plus il remonte).
`scoringTargets.rooms`	number	Non	Nombre de pièces cible. Les candidats au même `main_rooms` reçoivent un bonus.
`scoringTargets.isNewBuild`	boolean	Non	Bien neuf cible. Les candidats au même `is_new_build` reçoivent un bonus.
`scoringTargets.transactionType`	enum	Non	Nature de transaction cible : `Vente`, `Vente en l'etat futur d'achevement`, `Vente terrain a batir`, `Echange`.

Les clés de filters et scoringTargets sont en camelCase. Les résultats sont triés par score décroissant.

Réponse

L’API retourne un objet { data, meta }.

{
  "data": [
    {
      "score": 92.4,
      "confidence": "HIGH",
      "dvf": {
        "id": "2014-871319",
        "transaction_date": "2014-06-12T00:00:00.000Z",
        "transaction_type": "Vente",
        "price_eur": 265788,
        "price_per_m2_living_eur": 558,
        "postal_code": "83000",
        "insee_code": "83137",
        "property_type": "Appartement",
        "surface_m2": 476,
        "main_rooms": 3,
        "is_new_build": false,
        "location": { "lat": 43.12, "lon": 5.93 }
      }
    }
  ],
  "meta": {
    "total": 2,
    "ambiguous": false
  }
}

data[].score — similarité de 0 à 100.
data[].confidence — HIGH / MEDIUM / LOW / REJECT.
data[].dvf — sous-ensemble projeté de la transaction DVF (id, transaction_date, transaction_type, price_eur, surface_m2, main_rooms, is_new_build, location, etc.).
meta.total — nombre total de candidats trouvés après pré-filtrage.
meta.ambiguous — true si l’écart de score entre les deux premiers résultats est ≤ 5 points.

Le contrat complet champ par champ est décrit par le bloc OpenAPI plus bas (POST /v2/protected/opendata/dvf/match).

Exemple

Lookup exact par `mutationId`

Lorsque vous connaissez déjà l’identifiant de mutation, le pré-filtre mutationId cible une transaction précise. Le résultat est unique avec un score de 100.

curl -X POST https://api.fluximmo.io/v2/protected/opendata/dvf/match \
  -H "x-api-key: $FLUXIMMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "codeDepartement": "83",
      "postalCode": "83000",
      "mutationId": "2014-871319"
    }
  }'

Match multi-critères avec ancres de scoring

Cas typique : vous décrivez un bien (zone, type, bande de surface) via filters, puis vous affinez le classement avec scoringTargets (prix, pièces, nature de transaction).

curl -X POST https://api.fluximmo.io/v2/protected/opendata/dvf/match \
  -H "x-api-key: $FLUXIMMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "codeDepartement": "83",
      "postalCode": "83000",
      "propertyType": "Appartement",
      "surface": { "min": 450, "max": 500 },
      "location": { "lat": 43.1242, "lon": 5.928, "distance": "5km" }
    },
    "scoringTargets": {
      "price": 265000,
      "rooms": 3,
      "isNewBuild": false,
      "transactionType": "Vente"
    },
    "size": 5
  }'

Match d’un bien neuf (VEFA)

L’ancre isNewBuild: true combinée à la nature Vente en l'etat futur d'achevement (l’enum contient des apostrophes, à échapper en shell) favorise les transactions de logements neufs.

curl -X POST https://api.fluximmo.io/v2/protected/opendata/dvf/match \
  -H "x-api-key: $FLUXIMMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filters": {
      "codeDepartement": "83",
      "postalCode": "83000",
      "propertyType": "Maison",
      "surface": { "min": 100, "max": 140 }
    },
    "scoringTargets": {
      "price": 450000,
      "isNewBuild": true,
      "transactionType": "Vente en l'\''etat futur d'\''achevement"
    },
    "size": 3
  }'

Liens utiles

Recherche DVF — lister les transactions DVF par filtres, sans classement.
DVF vs Fluximmo — différence entre données DVF (transactions officielles) et annonces Fluximmo.

Clé test gratuite — 1 semaine

Créez un compte sur my.fluximmo.io pour récupérer une clé API test gratuite (1 semaine, accès limité). Aucun paiement requis.

Authorizations

x-api-key

string

header

required

Body

application/json

filters

object

Show child attributes

size

integer

default:5

Page size

Required range: 1 <= x <= 20

scoringTargets

object

Scoring anchors (price/rooms/isNewBuild/transactionType). Influence ranking only — do not exclude candidates.

Show child attributes

Response

Transactions DVF classées par score de similarité

data

object[]

required

Transactions DVF classées par score de similarité

Show child attributes

DPE

DVF

Documentation Index

​À quoi ça sert

​Payload

​Réponse

​Exemple

​Lookup exact par mutationId

​Match multi-critères avec ancres de scoring

​Match d’un bien neuf (VEFA)

​Liens utiles

Clé test gratuite — 1 semaine

Authorizations

Body

Response

À quoi ça sert

Payload

Réponse

Exemple

Lookup exact par `mutationId`

Match multi-critères avec ancres de scoring

Match d’un bien neuf (VEFA)

Liens utiles