> ## 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 DPE à une annonce (V2 stable)
> Retourne les DPE ADEME les plus similaires à une annonce immobilière, classés par score de similarité avec un niveau de confiance.
## À quoi ça sert
`POST /v2/protected/opendata/dpe/match` recherche, parmi les DPE de la base ADEME, les candidats les plus proches d'une annonce immobilière donnée. Contrairement à [DPE Search](/api-v2-reference/dpe-search/recherche-dpe) qui renvoie une liste paginée et filtrée, Match renvoie les meilleurs candidats **classés par similarité** et accompagnés d'un score.
Le payload sépare deux notions à ne pas confondre :
* **`filters` (pré-filtre dur)** — exclut les candidats qui ne correspondent pas (géographie, plage de surface, type de bâtiment, plage de dates, codes ADEME/BAN). Un candidat hors de ces bornes n'apparaît jamais dans la réponse.
* **`scoring_targets` (ancres douces)** — n'excluent rien. Elles influencent uniquement le classement : un candidat proche d'une ancre remonte dans le ranking, un candidat éloigné reste présent mais plus bas.
Chaque résultat porte un `score` normalisé de 0 à 100 et un `confidence` (`HIGH`, `MEDIUM`, `LOW`, `REJECT`). L'objet `meta` indique le nombre total de candidats trouvés et un drapeau `ambiguous`, vrai lorsque les deux premiers scores diffèrent de 5 points ou moins — utile pour signaler un match incertain à arbitrer manuellement.
Cas d'usage typiques : retrouver le DPE exact d'une annonce, rapprocher un lot d'annonces de leurs DPE pour enrichir un portefeuille, ou estimer l'étiquette énergétique probable d'un bien à partir de ses caractéristiques.
## Payload
Le corps de requête est un objet JSON.
| Champ | Type | Obligatoire | Sens |
| ----------------- | ------- | ----------- | ------------------------------------------------- |
| `filters` | object | Non | Pré-filtre dur. Voir le détail ci-dessous. |
| `size` | integer | Non | Nombre de candidats retournés (1–20, défaut `5`). |
| `scoring_targets` | object | Non | Ancres de scoring. Voir le détail ci-dessous. |
### `filters` (pré-filtre dur)
| Champ | Type | Sens |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `code_departement_ban` | string | Code département BAN (2–3 caractères, ex. `75`, `2A`, `974`). |
| `code_insee_ban` | string | Code INSEE de la commune (5 caractères). |
| `code_postal_ban` | string | Code postal (5 chiffres). |
| `numero_dpe` | string | Numéro unique du DPE attribué par l'ADEME. Recherche par identifiant. |
| `type_batiment` | string | `appartement`, `maison` ou `immeuble`. |
| `surface_habitable_logement` | object | Plage de surface habitable en m² : `{ "min": number, "max": number }`. |
| `date_etablissement_dpe` | object | Plage de dates d'établissement : `{ "from": "YYYY-MM-DD", "to": "YYYY-MM-DD" }`. |
| `location` | object | Filtre géographique : `{ "lat": number, "lon": number, "distance": "10km" }`. Unités acceptées : `m`, `km`, `mi`, `ft`, `yd`, `nmi`. |
### `scoring_targets` (ancres douces)
| Champ | Type | Sens |
| ------------------------------ | ------ | ---------------------------------------------------------------------------- |
| `conso_5_usages_par_m2_ep` | number | Consommation cible en kWh/m²/an. Rapproche les candidats à conso proche. |
| `emission_ges_5_usages_par_m2` | number | Émissions GES cibles en kgCO₂/m²/an. |
| `etiquette_dpe` | string | Étiquette énergie cible (`A`–`G`). Bonus de score si correspondance. |
| `etiquette_ges` | string | Étiquette GES cible (`A`–`G`). Bonus de score si correspondance. |
| `nombre_niveau_immeuble` | number | Nombre de niveaux de l'immeuble (0–200). |
| `numero_etage_appartement` | number | Étage de l'appartement (−10 à 200 ; valeur négative = sous-sol). |
| `periode_construction` | string | Période de construction cible (ex. `avant 1948`, `1948-1974`, `après 2021`). |
| `nombre_niveau_logement` | number | Nombre de niveaux du logement (0–200). |
## Réponse
L'API retourne un objet `{ data, meta }`.
`data` est un tableau de candidats classés par `score` décroissant. Chaque entrée contient :
| Champ | Type | Sens |
| ------------ | ------ | ---------------------------------------------------------- |
| `score` | number | Score de similarité normalisé (0–100). |
| `confidence` | string | Niveau de confiance : `HIGH`, `MEDIUM`, `LOW` ou `REJECT`. |
| `dpe` | object | Champs clés du DPE retenu (projection Match). |
L'objet `dpe` expose notamment `numero_dpe`, `adresse_ban`, `location` (`{ lat, lon }`), `etiquette_dpe`, `etiquette_ges`, `conso_5_usages_par_m2_ep`, `emission_ges_5_usages_par_m2`, `surface_habitable_logement`, `date_etablissement_dpe` et `date_fin_validite_dpe`.
`meta` contient :
| Champ | Type | Sens |
| ----------- | ------- | ------------------------------------------------------------------ |
| `total` | number | Nombre total de candidats trouvés (au-delà de `size`). |
| `ambiguous` | boolean | `true` si les deux premiers scores diffèrent de 5 points ou moins. |
Le contrat exact est documenté plus bas par le bloc OpenAPI (`POST /v2/protected/opendata/dpe/match`).
## Exemple
### Recherche par numéro de DPE
Lookup direct par identifiant ADEME : la recherche court-circuite le scoring et retourne le DPE correspondant.
```bash theme={null}
curl -X POST https://api.fluximmo.io/v2/protected/opendata/dpe/match \
-H "x-api-key: $FLUXIMMO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filters": {
"code_departement_ban": "75",
"code_postal_ban": "75009",
"numero_dpe": "2675E0698907D"
}
}'
```
### Match multi-critères avec ancres de scoring
Pré-filtre dur sur la zone, le type et la plage de surface, puis classement affiné par quatre ancres douces.
```bash theme={null}
curl -X POST https://api.fluximmo.io/v2/protected/opendata/dpe/match \
-H "x-api-key: $FLUXIMMO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"filters": {
"code_departement_ban": "75",
"code_postal_ban": "75011",
"type_batiment": "appartement",
"surface_habitable_logement": { "min": 45, "max": 60 },
"location": { "lat": 48.8592, "lon": 2.3789, "distance": "2km" }
},
"scoring_targets": {
"etiquette_dpe": "D",
"etiquette_ges": "C",
"conso_5_usages_par_m2_ep": 210,
"nombre_niveau_immeuble": 6
},
"size": 5
}'
```
## Liens utiles
* [DPE Search — recherche paginée](/api-v2-reference/dpe-search/recherche-dpe) — liste filtrée de DPE, sans scoring.
* [DVF vs Fluximmo](/concepts/dvf-vs-fluximmo) — comprendre les sources de données open data.
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/dpe/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/dpe/match:
post:
tags:
- DPE Match
summary: Match DPE à une annonce immobilière
description: >-
Recherche les DPE les plus similaires à une annonce immobilière en se
basant sur la localisation, la surface, les étiquettes énergie/GES, et
d'autres critères. Retourne les meilleurs candidats avec un score de
confiance.
operationId: MatchDpeController_postMatch
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MatchDpeDto'
responses:
'200':
description: Candidats DPE classés par score de similarité
content:
application/json:
schema:
$ref: '#/components/schemas/MatchDpeResponseDto'
'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:
MatchDpeDto:
type: object
properties:
filters:
$ref: '#/components/schemas/DpeFiltersDto'
size:
type: integer
minimum: 1
maximum: 20
default: 5
description: Page size
scoring_targets:
description: >-
Scoring anchors
(conso_5_usages_par_m2_ep/emission_ges_5_usages_par_m2/etiquette_dpe/etiquette_ges/nombre_niveau_immeuble).
Influence ranking only — do not exclude candidates.
allOf:
- $ref: '#/components/schemas/MatchDpeScoringTargetsDto'
MatchDpeResponseDto:
type: object
properties:
data:
description: Candidats DPE classés par score de similarité
type: array
items:
$ref: '#/components/schemas/MatchDpeEntryResponseDto'
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
DpeFiltersDto:
type: object
properties:
code_departement_ban:
type: string
description: 'Code du département (BAN, 2-3 caractères, ex : 75, 2A, 974)'
example: '75'
code_insee_ban:
type: string
description: Code INSEE de la commune (BAN, 5 caractères)
example: '75113'
code_postal_ban:
type: string
description: Code postal (BAN, 5 chiffres)
example: '75013'
numero_dpe:
type: string
description: Numéro unique du DPE attribué par l'ADEME
example: 2600E0590119C
type_batiment:
type: string
description: 'Type de bâtiment. Possible values: appartement, maison, immeuble'
example: appartement
surface_habitable_logement:
description: Surface habitable du logement en m²
example:
min: 57
allOf:
- $ref: '#/components/schemas/NumberRangeFilter'
date_etablissement_dpe:
description: Date d'établissement du DPE
example:
from: '2023-06-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'
MatchDpeScoringTargetsDto:
type: object
properties:
conso_5_usages_par_m2_ep:
type: number
description: >-
Scoring anchor (gauss decay, scale=50 kWh/m²). Candidates with
similar conso_5_usages_par_m2_ep rank higher.
example: 210
minimum: 0
emission_ges_5_usages_par_m2:
type: number
description: >-
Scoring anchor (gauss decay, scale=10 kgCO₂/m²). Candidates with
similar emission_ges_5_usages_par_m2 rank higher.
example: 18
minimum: 0
etiquette_dpe:
type: string
description: >-
Scoring anchor (weighted filter). Candidates matching this DPE label
receive a score boost.
enum:
- D
- E
- C
- F
- G
- B
- A
example: D
etiquette_ges:
type: string
description: >-
Scoring anchor (weighted filter). Candidates matching this GES label
receive a score boost.
enum:
- C
- B
- D
- A
- E
- F
- G
example: C
nombre_niveau_immeuble:
type: number
description: >-
Scoring anchor (weighted filter). Candidates with the same
nombre_niveau_immeuble receive a score boost.
example: 6
minimum: 0
maximum: 200
numero_etage_appartement:
type: number
description: >-
Scoring anchor (weighted filter). Candidates with the same
numero_etage_appartement receive a score boost. Negative values
denote a basement floor.
example: 3
minimum: -10
maximum: 200
periode_construction:
type: string
description: >-
Scoring anchor (weighted filter). Candidates matching this
periode_construction receive a score boost.
enum:
- avant 1948
- 1948-1974
- 1989-2000
- 1978-1982
- 1975-1977
- 2006-2012
- 2013-2021
- 1983-1988
- 2001-2005
- après 2021
example: 1948-1974
nombre_niveau_logement:
type: number
description: >-
Scoring anchor (weighted filter). Candidates with the same
nombre_niveau_logement receive a score boost.
example: 2
minimum: 0
maximum: 200
MatchDpeEntryResponseDto:
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
dpe:
type: object
description: Champs clés du DPE (projection MATCH)
properties:
numero_dpe:
type: string
description: Numéro unique du DPE attribué par l'ADEME
adresse_ban:
type: string
description: Adresse complète normalisée BAN
location:
type: object
properties:
lat:
oneOf:
- type: number
- type: string
pattern: ^-?\d+(\.\d+)?$
lon:
oneOf:
- type: number
- type: string
pattern: ^-?\d+(\.\d+)?$
description: Coordonnées géographiques du bien (latitude, longitude)
example:
lat: 48.8566
lon: 2.3522
etiquette_dpe:
type: string
description: >-
Étiquette énergie du DPE (A = meilleur, G = pire, N = non
applicable)
etiquette_ges:
type: string
description: >-
Étiquette GES du DPE (A = meilleur, G = pire, N = non
applicable)
conso_5_usages_par_m2_ep:
type: number
description: Consommation des 5 usages en énergie primaire par m² (kWh/m²/an)
emission_ges_5_usages_par_m2:
type: number
description: Émissions de GES des 5 usages par m² (kgCO₂/m²/an)
surface_habitable_logement:
type: number
description: Surface habitable du logement en m²
date_etablissement_dpe:
type: string
description: Date d'établissement du DPE
example: '2023-06-15'
format: date-time
date_fin_validite_dpe:
type: string
description: Date de fin de validité du DPE (10 ans après établissement)
example: '2033-06-15'
format: date-time
required:
- score
- confidence
- dpe
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
````