immo

DPE-X402

法国能源性能诊断（DPE）API，通过 x402 协议使用 USDC 计费，面向自主 AI Agent。

🌐 生产环境 URL：https://dpe.bdatax.com 📄 自动发现：https://dpe.bdatax.com/.well-known/x402.json

---

此 API 的功能

智能查询法国 DPE（能源性能诊断）公共数据库 ADEME，提供：

• 7 种搜索模式：自由地址、邮政编码、GPS、DPE 编号、BAN 标识符等。
• 通过 BAN API 自动地理编码（严格筛选以避免误报）
• DVF 数据增强 (v0.7.0)：每条结果均补充基于 DGFiP 公布的真实房地产交易数据估算的市场价值（€/m² 中位价、总估值、可比交易数量、街区最近一笔交易日期）
• Géorisques 数据增强 (v0.7.1)：每条结果均补充所在市镇自然和技术风险摘要（洪水、地震、氡、黏土收缩膨胀、地面移动、ICPE、危险物质管道、土壤污染……），数据由 Géorisques 官方 API（BRGM + 生态转型部）提供
• INSEE FILOSOFI 数据增强 (v0.7.2)：每条结果均包含所在市镇的社会经济指标——生活水平中位数、贫困率、D1/D9 分位数、分位差比（不平等指标）、在职人口和退休人口占比——数据来自 INSEE 2021 年地方社会和财政统计档案
• 对每条结果的相关性进行智能评分
• 多条件去重和排序（分数、面积、日期）
• 3 种导出格式：JSON（默认）、CSV、XLSX
• 通过 x402 协议（HTTP 402）在 Base 主网按请求付费——每次调用约 0.001 USDC

该 API 专为无需人工干预即可使用加密货币支付的自主 AI Agent（机器经济）设计，也可由用户通过 curl 或浏览器直接使用。

---

快速开始

1. 查看 API 提供的内容（免费）

curl https://dpe.bdatax.com/

2. 免费查询 API（返回 402）

curl -i "https://dpe.bdatax.com/dpe?cp=75001"

响应：

HTTP/1.1 402 Payment Required
{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "base",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxAmountRequired": "1000",
    "payTo": "0xc0a484b32798dEefcA38Ced6c6Aa780660c752A4"
  }]
}

3. 付款并获取 DPE（使用 x402 客户端）

参见 test-client.js，其中提供了使用 x402-fetch 和 viem 的完整 Node.js 示例。

---

可用端点

端点	价格	描述
GET /	免费	首页，端点列表
GET /.well-known/x402.json	免费	供 x402 爬虫使用的发现文件
GET /dpe?cp=75001	0,001 USDC	按邮政编码搜索
GET /dpe?adresse=203 rue Saint-Honoré 75001 Paris	0,001 USDC	按自由地址搜索
GET /dpe?voie=Saint-Honoré&cp=75001	0,001 USDC	按街道名称搜索
GET /dpe?numero=203&voie=Saint-Honoré&cp=75001	0,001 USDC	按门牌号 + 街道 + 邮政编码搜索
GET /dpe?numeroDPE=2175E0465600P	0,001 USDC	按 DPE 标识符搜索
GET /dpe?lat=48.864968&lon=2.331665	0,001 USDC	按 GPS 坐标搜索
GET /dpe?cp=75001&format=csv	0,001 USDC	导出 CSV（兼容法国 Excel）
GET /dpe?cp=75001&format=xlsx	0,001 USDC	导出原生 Excel 格式

每次调用 /dpe 都会返回结构化 JSON，包含 meilleurResultat、resultats（排序后的数组）、dpeLePlusRecent 和搜索元数据。

---

DVF 数据增强 (v0.7.0 新增)

返回的每条 DPE 都会自动补充来自公共数据库 DVF（Demandes de Valeurs Foncières，DGFiP）的房地产市场数据，无需额外付费：

{
  "adresse": "14 rue Vauvilliers 75001 Paris",
  "etiquetteDPE": "F",
  "surfaceM2": 22.9,
  "coutAnnuelTotal": 1168,
  "dvf": {
    "prixMedianM2": 12400,
    "prixEstimeTotal": 283960,
    "nbTransactionsComparables": 8,
    "derniereTransaction": "2025-11-14",
    "rayonMetres": 200,
    "ecartSurfacePct": 30
  }
}

方法：对于每条带有地理位置的 DPE，会在 200 m 半径范围内查找近期（2024-2025）、类型相同（公寓 / 独栋住宅）且面积相近（±30 %）的房地产交易。随后计算每平方米价格的中位数，并将其应用于 DPE 的面积。

如果样本量过少（少于 3 笔可比交易），或所在省份尚未编入索引，dvf 的值为 null。此字段始终存在，以便 API 使用方统一测试其是否存在。

覆盖范围：法国全境（本土 + DROM），交易数据更新至 DGFiP 最近一次半年更新。

更新 DVF 索引：每年两次（4 月和 10 月），下载新版 full.csv.gz 文件后，在本地运行 node build-dvf-index.js，然后推送 data/dvf/。新版文件可从 data.gouv.fr 下载。

---

Géorisques 数据增强 (v0.7.1 新增)

返回的每条 DPE 还会补充其所在市镇面临的自然和技术风险概要，用户无需额外付费。数据来自由 BRGM 和生态转型部维护的官方 Géorisques API：

{
  "adresse": "203 Rue Saint-Honoré 75001 Paris",
  "etiquetteDPE": "F",
  "codeInsee": "75101",
  "georisques": {
    "commune": "PARIS 1ER ARRONDISSEMENT",
    "codeInsee": "75101",
    "risquesNaturels": {
      "inondation": "existant",
      "seisme": "faible",
      "retraitGonflementArgile": "important",
      "radon": "faible",
      "mouvementTerrain": "existant",
      "remonteeNappe": "existant"
    },
    "risquesTechnologiques": {
      "icpe": "concerne",
      "canalisationsMatieresDangereuses": "concerne",
      "pollutionSols": "concerne"
    },
    "nbRisquesPresents": 9,
    "sourceUrl": "https://www.georisques.gouv.fr/mes-risques/..."
  }
}

方法：从 DPE 的 identifiantBAN 字段中提取市镇的 INSEE 代码，然后查询 Géorisques 的 /api/v1/resultats_rapport_risque 端点。响应按 INSEE 代码在 RAM 中缓存 24 h——即使同一市镇有 1000 条 DPE，每天也只会触发一次 API 调用。

如果无法提取 codeInsee（DPE 不含 identifiantBAN）、Géorisques API 返回错误，或超时时间超过 5 s，georisques 的值为 null。服务会优雅降级：响应中的其他字段（DPE + DVF）仍会正常返回。

典型用例：保险公司（计算保费）、银行（分析房地产信贷风险）、房地产代币化平台（自动化尽职调查）、自主房地产 AI Agent。

---

与 Node.js 客户端搭配使用

安装：

npm install x402-fetch viem

使用：

import { wrapFetchWithPayment } from "x402-fetch";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.PRIVATE_KEY);
const fetchWithPayment = wrapFetchWithPayment(fetch, account, BigInt(10_000));

const response = await fetchWithPayment(
  "https://dpe.bdatax.com/dpe?cp=75001"
);
const data = await response.json();
console.log(data.meilleurResultat);

test-client.js 中提供了带注释的完整示例。

测试前需要：

1. 一个 EVM 钱包，其中在 Base 主网上有少量 USDC（从 Arbitrum、Ethereum 跨链转入，或直接在 Coinbase 购买）
2. 创建文件 client.env，并填写 PRIVATE_KEY=...（切勿提交！）
3. 运行：node --env-file=client.env test-client.js

---

架构

每次 /dpe 请求都会经过以下 12 个步骤：

1. x402 中间件（支付）
2. 提取搜索条件
3. 自动分析地址（regex）
4. BAN 逆向地理编码（GPS → 地址）
5. BAN 正向地理编码（地址 → GPS，并严格验证 CP / 市镇）
6. 并行发送 ADEME 请求（Promise.all）
7. 为每条 DPE 评分（经校准的评分标准）
8. 去重并按多项条件排序
9. DVF 数据增强——对每条结果，在本地查询可比房地产交易（内存中的 LRU 缓存）
10. Géorisques 数据增强——按 INSEE 代码调用 /resultats_rapport_risque API（RAM 缓存 24 h）
11. INSEE FILOSOFI 数据增强——按 INSEE 代码在本地查询收入 / 贫困 / 分位数数据（LRU 缓存）
12. 按要求的格式输出（JSON / CSV / XLSX）

典型响应时间：< 800 ms（对每个市镇的首次调用中，Géorisques 会增加约 200-400 ms；之后从缓存提供结果；DVF 和 INSEE 数据均在本地查询，只需几毫秒）。

---

路线图

• v0.7.0 ✅ DVF 数据增强（房地产交易、中位价 €/m²）
• v0.7.1 ✅ Géorisques 数据增强（洪水、地震、氡、污染、ICPE、黏土……）
• v0.7.2 ✅ INSEE FILOSOFI 数据增强（收入中位数、贫困率、十分位数）
• v0.8.x：房产评分（翻新、夏季舒适度、整体吸引力）
• v0.9.x：收费标准不同的 /dpe/enrichi 端点（约 0.02 USDC）
• v1.0：整合、公开 SLA、合作伙伴仪表板

---

归属

• DPE 数据：ADEME — 开放数据
• 土地价值数据（DVF）：DGFiP / Etalab — 开放数据
• 自然与技术风险：Géorisques — BRGM 和生态转型部
• 按市镇划分的收入与贫困数据：INSEE FILOSOFI 2021 — 开放许可
• 地理编码：Base Adresse Nationale — 开放数据
• 支付协议：x402 — 由 Coinbase 推动的 HTTP 402 标准

---

技术栈

• 运行时：Node.js + Express 5
• 支付：x402-express，运行于 Base
• Excel 导出：SheetJS
• 托管：Render.com（法兰克福）
• DNS：Cloudflare

---

品牌

BData X — 基于公开数据、通过 x402 变现的法国 API 组合。

---

许可证

本项目依据 Business Source License 1.1（BSL）发布 — 详见 LICENSE。

简而言之：

• ✅ 你可以自由地研究、分叉、修改代码
• ✅ 你可以将其用于个人或内部项目
• ✅ 你可以通过拉取请求贡献
• ❌ 你不得将其用于打造与 dpe.bdatax.com 竞争的商业 SaaS

2030 年 8 月 27 日，此许可证将自动转为 Apache 2.0（完全开放）。

如需在此日期前将其用于竞争性商业用途，请通过代码仓库联系。