> ## Documentation Index
> Fetch the complete documentation index at: https://doc.fluximmo.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Match DVF à un bien (V2 stable)
> Retourne les transactions DVF les plus similaires à un bien immobilier connu, classées par score de similarité.
## À 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](/api-v2-reference/dvf-search/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.
* **`scoring_targets` (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.departement_code` | string | Non | Code du département (2-3 caractères, ex : `75`, `2A`, `974`). |
| `filters.insee_code` | string | Non | Code INSEE de la commune (5 caractères). |
| `filters.postal_code` | string | Non | Code postal (5 chiffres). |
| `filters.id` | string | Non | Identifiant unique d'une mutation DVF. Permet un lookup exact d'une transaction connue. |
| `filters.property_type` | enum | Non | Type de bien : `Appartement`, `Maison`, `Autre`, `Terrain`, `Tertiaire`, `Dépendance`, `Volume`. |
| `filters.surface_m2` | objet `{ min, max }` | Non | Bande de surface habitable en m². |
| `filters.transaction_date` | 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`. |
| `scoring_targets` | objet | Non | Ancres de scoring. Influencent le classement sans exclure de candidats. |
| `scoring_targets.price_eur` | number | Non | Prix cible en euros (décroissance gaussienne : plus le candidat est proche, plus il remonte). |
| `scoring_targets.main_rooms` | number | Non | Nombre de pièces cible. Les candidats au même `main_rooms` reçoivent un bonus. |
| `scoring_targets.is_new_build` | boolean | Non | Bien neuf cible. Les candidats au même `is_new_build` reçoivent un bonus. |
| `scoring_targets.transaction_type` | enum | Non | Nature de transaction cible : `Vente`, `Vente en l'etat futur d'achevement`, `Vente terrain a batir`, `Echange`. |
Les résultats sont triés par `score` décroissant.
## Réponse
L'API retourne un objet `{ data, meta }`.
```json theme={null}
{
"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 `id`
Lorsque vous connaissez déjà l'identifiant de mutation, le pré-filtre `id` cible une transaction précise. Le résultat est unique avec un `score` de `100`.
```bash theme={null}
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": {
"departement_code": "83",
"postal_code": "83000",
"id": "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 `scoring_targets` (prix, pièces, nature de transaction).
```bash theme={null}
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": {
"departement_code": "83",
"postal_code": "83000",
"property_type": "Appartement",
"surface_m2": { "min": 450, "max": 500 },
"location": { "lat": 43.1242, "lon": 5.928, "distance": "5km" }
},
"scoring_targets": {
"price_eur": 265000,
"main_rooms": 3,
"is_new_build": false,
"transaction_type": "Vente"
},
"size": 5
}'
```
### Match d'un bien neuf (VEFA)
L'ancre `is_new_build: 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.
```bash theme={null}
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": {
"departement_code": "83",
"postal_code": "83000",
"property_type": "Maison",
"surface_m2": { "min": 100, "max": 140 }
},
"scoring_targets": {
"price_eur": 450000,
"is_new_build": true,
"transaction_type": "Vente en l'\''etat futur d'\''achevement"
},
"size": 3
}'
```
## Liens utiles
* [Recherche DVF](/api-v2-reference/dvf-search/recherche-dvf) — lister les transactions DVF par filtres, sans classement.
* [DVF vs Fluximmo](/concepts/dvf-vs-fluximmo) — différence entre données DVF (transactions officielles) et annonces Fluximmo.
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.
## OpenAPI
````yaml post /v2/protected/opendata/dvf/match
openapi: 3.0.0
info:
title: Real-estate data API - Fluximmo V2
description: >+
## Fluximmo
##### Real-time real estate data: Power workflows, business applications and
decision-making.
Real estate expert since 2017, Fluximmo aggregates, exploits, enriches &
analyzes the
real-estate market in real time to offer data flows, APIs and innovative
services to real estate professionals.
## Authentification
You'll need to be authenticated with an active subscription to access our
REST endpoints.
To get an API-KEY please contact us at contact@fluximmo.com or book a call
with our team: https://calendly.com/fluximmo/meet-fluximmo
##### How to use your API KEY
Simply add to your HTTP request your API KEY in the headers:
`{'x_api_key':'randomApiKey'}`
## Properties and Adverts
Real-estate market can be conceptualized in different ways. We offer two
different conceptualization depending on your needs: Properties & Adverts.
#### Properties (BAAS)
A property is a real-estate habitation/land/commercial/building to which is
attached adverts.
We gather all the adverts offering (selling or renting) this real-estate
asset and consolidate all the information into one Property.
A Property is by definition `de-duplicated` and can gather 1 to x adverts:
these adverts are either duplicates from different portals or with mandates
from different agencies or republication of the same advertising with a
price update or not.
The concept of property is in constant mutation until the real-estate asset
is sold: We'll keep merging new adverts within the Property concept and
update the price if needed.
By it's nature in constant mutation, we do not offer the possibility to
receive these Properties on webhooks. You'll need to use our APIs as a
Backend As A Service (BaaS).
#### Adverts (BAAS and WEBHOOK)
Adverts are advertising of a real-estate property. Adverts can come from
many sources: Agencies websites, Aggregation real-estate portals,
Social-Networks, NewsPaper etc...
After gathering all these adverts our proprietary AI algorithms will
de-duplicate these adverts and associate them to a Property
An advert have a unique URL. Meaning that the same advertising re-published
twice (with our without any change, on the same website or not, by the same
agency or not) is considered as 2 ads.
You can choose either to retrieve all the Adverts or only the non duplicated
ones. Adverts can be retrieved either by API (Search or Alerts) or Webhook
## Webhooks
We offer the possibility to receive our real-estate Adverts data in
real-time using webhooks. As soon as we gather the data, you'll receive it
few moments later.
Using ALERTS, you can receive new adverts matching your criteria on a
webhook.
##### Webhook differences between Adverts and Properties
As Properties are by nature in perpetual evolutions (new duplicated ads will
be merged, new data to be consolidated etc..), we do not offer the
possibility to receive through Webhooks the full body of the properties.
Properties webhook will only send you the list of the properties FlxIds
matching your search.
You'll find below the schema of the data you would receive on your webhook
(`/v2/sample/webhook/properties`, `/v2/sample/webhook/adverts`)
##### What is a webhook
A webhook can be thought of as a type of API that is driven by events rather
than requests
.Instead of one application making a request to another to receive a
response, a webhook is a service that allows one program to send data to
another as soon as a particular event takes place.
Webhooks are sometimes referred to as “reverse APIs,” because communication
is initiated by the application sending the data rather than the one
receiving it.
With web services becoming increasingly interconnected, webhooks are seeing
more action as a lightweight solution for enabling real-time notifications
and data updates without the need to develop a full-scale API.
##### When to use a webhook instead of the REST API
You're supposed to receive a high volume of data (frequently or not), you're
looking for real-time data, you just have to relax and wait (no cron, no
call on our API etc..)
##### Webhook implementation examples
A webhook is simply a POST endpoint we can request
* Python:
https://gist.github.com/aloysius-tim/293772256526efa20d5c625c6ace036a
* Node:
https://gist.github.com/aloysius-tim/ea1d9feb2c527b5b09ffc356b662d14b
version: 2.0.0
contact: {}
x-logo:
url: https://www.fluximmo.com/assets/images/logo_text.png
backgroundColor: '#F31051'
altText: Fluximmo logo
servers:
- url: https://api.fluximmo.io
security: []
tags:
- name: PropertyModel
description:
- name: AdvertModel
description:
paths:
/v2/protected/opendata/dvf/match:
post:
tags:
- DVF Match
summary: Match DVF à un bien immobilier
description: >-
Recherche les transactions DVF les plus similaires à un bien immobilier
en se basant sur la localisation, la surface, le prix, le type de bien,
et la date de transaction. Retourne les meilleurs candidats avec un
score de confiance.
operationId: MatchDvfController_postMatch
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MatchDvfDto'
responses:
'200':
description: Transactions DVF classées par score de similarité
content:
application/json:
schema:
$ref: '#/components/schemas/MatchDvfResponseDto'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionDto'
'401':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ExceptionDto'
security:
- x_api_key: []
components:
schemas:
MatchDvfDto:
type: object
properties:
filters:
$ref: '#/components/schemas/DvfFiltersDto'
size:
type: integer
minimum: 1
maximum: 20
default: 5
description: Page size
scoring_targets:
description: >-
Scoring anchors
(price_eur/main_rooms/is_new_build/transaction_type). Influence
ranking only — do not exclude candidates.
allOf:
- $ref: '#/components/schemas/MatchDvfScoringTargetsDto'
MatchDvfResponseDto:
type: object
properties:
data:
description: Transactions DVF classées par score de similarité
type: array
items:
$ref: '#/components/schemas/MatchDvfEntryResponseDto'
meta:
description: Métadonnées du matching
allOf:
- $ref: '#/components/schemas/MatchMetaResponseDto'
required:
- data
- meta
ExceptionDto:
type: object
properties:
error:
description: Error object
allOf:
- $ref: '#/components/schemas/ErrorDto'
required:
- error
DvfFiltersDto:
type: object
properties:
departement_code:
type: string
description: 'Code du département (2-3 caractères, ex : 75, 2A, 974)'
example: '83'
insee_code:
type: string
description: Code INSEE de la commune (5 caractères)
example: '83137'
postal_code:
type: string
description: Code postal (5 chiffres)
example: '83000'
id:
type: string
description: Identifiant unique de la mutation DVF
example: 2014-871319
property_type:
type: string
description: >-
Type de bien principal de la transaction. Possible values:
Appartement, Maison, Autre, Terrain, Tertiaire, Dépendance, Volume
example: Appartement
surface_m2:
description: Surface habitable principale du bien en m²
example:
min: 476
allOf:
- $ref: '#/components/schemas/NumberRangeFilter'
transaction_date:
description: Date de la transaction immobilière
example:
from: '2023-09-15'
allOf:
- $ref: '#/components/schemas/DateRangeFilter'
location:
description: Coordonnées géographiques du bien (latitude, longitude)
example:
lat: 48.8566
lon: 2.3522
distance: 10km
allOf:
- $ref: '#/components/schemas/GeoDistanceFilter'
MatchDvfScoringTargetsDto:
type: object
properties:
price_eur:
type: number
description: >-
Scoring anchor (gauss decay). Candidates closer to this price rank
higher; far candidates are not excluded.
example: 285000
minimum: 0
main_rooms:
type: number
description: >-
Scoring anchor (weighted filter). Candidates with the same
main_rooms count receive a score boost.
example: 3
minimum: 0
is_new_build:
type: boolean
description: >-
Scoring anchor (weighted filter). Candidates matching is_new_build
receive a score boost.
example: true
transaction_type:
type: string
description: >-
Scoring anchor (weighted filter). Candidates with the same
transaction_type receive a score boost.
enum:
- Vente
- Vente en l'etat futur d'achevement
- Vente terrain a batir
- Echange
example: Vente
MatchDvfEntryResponseDto:
type: object
properties:
score:
type: number
description: Score normalisé de similarité (0–100)
example: 85.3
confidence:
type: string
description: Niveau de confiance du match
enum:
- HIGH
- MEDIUM
- LOW
- REJECT
example: HIGH
dvf:
type: object
description: >-
Transaction DVF (champs essentiels) — sous-ensemble projeté du
document Elasticsearch
properties:
id:
type: string
description: Identifiant unique de la mutation DVF
transaction_date:
type: string
description: Date de la transaction immobilière
example: '2023-09-15'
format: date-time
transaction_type:
type: string
description: Nature de la mutation (vente, adjudication, échange, etc.)
price_eur:
type: number
description: Prix de la transaction en euros
price_per_m2_living_eur:
type: number
description: Prix au m² de surface habitable en euros
price_per_m2_land_eur:
type: number
description: Prix au m² de terrain en euros
location:
type: object
properties:
lat:
type: number
lon:
type: number
description: Coordonnées géographiques du bien (latitude, longitude)
example:
lat: 48.8566
lon: 2.3522
postal_code:
type: string
description: Code postal (5 chiffres)
insee_code:
type: string
description: Code INSEE de la commune (5 caractères)
address:
type: string
description: Adresse complète du bien
property_type:
type: string
description: Type de bien principal de la transaction
surface_m2:
type: number
description: Surface habitable principale du bien en m²
main_rooms:
type: integer
description: Nombre de pièces principales
is_new_build:
type: boolean
description: Indique si le bien est un logement neuf (VEFA ou première vente)
required:
- score
- confidence
- dvf
MatchMetaResponseDto:
type: object
properties:
ambiguous:
type: boolean
description: >-
Indique si les 2 premiers résultats ont des scores proches (écart ≤
5 points)
example: false
total:
type: number
description: Nombre total de candidats trouvés
example: 3
required:
- ambiguous
- total
ErrorDto:
type: object
properties:
message:
type: string
description: Error message
code:
type: number
description: Error code
required:
- message
- code
NumberRangeFilter:
type: object
properties:
min:
type: number
description: Minimum value (gte)
max:
type: number
description: Maximum value (lte)
DateRangeFilter:
type: object
properties:
from:
type: string
format: date-time
description: Start date (gte)
to:
type: string
format: date-time
description: End date (lte)
GeoDistanceFilter:
type: object
properties:
lat:
type: number
minimum: -90
maximum: 90
description: Latitude
lon:
type: number
minimum: -180
maximum: 180
description: Longitude
distance:
type: string
pattern: ^\d+(\.\d+)?(m|km|mi|ft|yd|nmi)$
example: 10km
description: Distance with unit
required:
- lat
- lon
- distance
securitySchemes:
x_api_key:
type: apiKey
in: header
name: x-api-key
````