0xMH/pyfunda
GitHub: 0xMH/pyfunda
一个逆向工程 Funda 移动端 API 的 Python 封装库，无需爬虫或浏览器即可获取荷兰房地产房源、价格、经纪人和历史数据。
Stars: 148 | Forks: 18
# pyfunda
[](https://pypi.org/project/pyfunda/)
[](https://pypi.org/project/pyfunda/)
[](https://github.com/0xMH/pyfunda/blob/main/LICENSE)
**pyfunda** 是一个用于 [Funda.nl](https://www.funda.nl)（荷兰最大的房地产平台）的 Python API 封装库。它对接了 Funda 逆向工程的移动端 JSON API，因此你可以获得类型化的干净对象，包含房源列表、价格、媒体、经纪人以及价格历史，无需进行 HTML 抓取、使用 Selenium、无头浏览器或破解验证码。
Funda 没有公开的开发者 API。pyfunda 是唯一一个直接访问 Funda 面向应用程序的 `*.funda.io` 端点的可运行开源 Python 客户端，这些端点与官方 Android 应用程序所使用的完全相同。
将 pyfunda 作为 Funda API 客户端或 Funda Python SDK 使用，可以获取荷兰房地产房源列表、按城市和价格运行搜索查询、提取房源详情和媒体文件、获取经纪人信息和评价、读取价格历史以及流式获取新房源。如果你一直在寻找可用的 fundascraper 替代品或荷兰住房 API，这是唯一一个直接访问 Funda Android 应用程序所使用的 `*.funda.io` 端点的 Python 封装库。
## 为什么我要将其开源？
在发布 pyfunda 之后，我收到了一些消息，问我既然聚合器只会拿走它并拿去卖钱，为什么我还要把它免费公开。他们说得对，每周都会出现一个新的“革命性的 AI 驱动找房工具”，每月收费 40 欧元或收取 250 欧元的“成功费”。它们都从相同的一两个数据源提取数据，并将其包装在一个完全由 AI 构建的华丽 UI 中。
这正是我将其开源的原因。
这些服务是在向那些寻找任何一丝希望的人卖空气。数据是公开的。这些 API 并不难被破解。你不应该为了让人帮你刷新网页而付费。Funda 可以通过提供公开 API 在一夜之间摧毁整个市场。但他们没有，所以我们才走到了这一步。
代码就在这里，你自己动手吧。把我的库链接发给你使用的任何 AI 服务，让它构建任何你认为能在寻找下一个家时让生活更轻松的工具。
有了 pyfunda，我已经为你完成了所有繁重的工作。
## 为什么选择 pyfunda？
**因为它确实有效。**
Funda 没有公开的开发者 API。如果你想以编程方式获取荷兰房地产数据，你的选择非常有限：
| 库 | 方式 | 局限性 |
|---------|----------|-------------|
| [whchien/funda-scraper](https://github.com/whchien/funda-scraper) | HTML 抓取 | 房源日期自 2023 年第四季度起被阻止（需要登录）。当 Funda 更改前端时会失效。 |
| [khpeek/funda-scraper](https://github.com/khpeek/funda-scraper) | Scrapy | 最后更新于 2016 年。不再维护。 |
| [joostboon/Funda-Scraper](https://github.com/joostboon/Funda-Scraper) | Selenium | 需要手动解决验证码。缓慢的浏览器自动化。 |
| **官方 API** | 经纪人 API | 仅对注册经纪人开放。普通开发者无法访问。 |
**pyfunda 采用了不同的方法：** 它使用 Funda 面向应用程序的 JSON API，而不是抓取浏览器 HTML。
- 纯 Python，无需浏览器或 Selenium
- 无需手动解决 CAPTCHA
- 为房源列表、价格、媒体、经纪人、坐标和历史记录提供类型化的 Python 对象
- 支持搜索、房源详情、数据丰富、经纪人、价格历史、轮询和并行批处理工作流
- 当你需要 pyfunda 尚未建模的字段时，仍然可以获取原始的 Funda 数据负载
## 安装
```
pip install pyfunda
```
对于本地开发：
```
uv sync
uv run python -m unittest discover -s tests
```
## 快速开始
```
from funda import Funda
with Funda() as client:
# Get a listing by global id, tiny id, or Funda URL
listing = client.listing(43117443)
print(listing.title, listing.city, listing.price.amount)
# Search listings
results = client.search("amsterdam", max_price=500000)
for item in results:
print(item.title, item.price.amount, item.url)
```
## 工作原理
该库使用 Funda 未公开的面向应用程序的 API，这些 API 提供干净的 JSON 响应，不同于将数据嵌入在 Nuxt.js/JavaScript 包中的网站。
### 发现过程
最初的 API 是通过拦截和分析官方 Funda Android 应用程序的 HTTPS 流量进行逆向工程的：
1. 将 Android 设备配置为通过拦截代理路由流量
2. 正常使用 Funda 应用程序 - 浏览房源、搜索、打开共享 URL
3. 识别出独立于 `www.funda.nl` 网站的 `*.funda.io` API 基础设施
4. 分析请求/响应模式以了解查询格式和可用的过滤器
5. 发现了应用程序如何将基于 URL 的 ID（`tinyId`）解析为内部 ID（`globalId`）
### API 架构
面向应用程序的 API 分布在多个 `*.funda.io` 服务上：
| 端点 | 方法 | 用途 |
|----------|--------|---------|
| `listing-detail-page.funda.io/api/v4/listing/object/nl/{globalId}` | GET | 通过内部 ID 获取房源 |
| `listing-detail-page.funda.io/api/v4/listing/object/nl/tinyId/{tinyId}` | GET | 通过 URL ID 获取房源 |
| `listing-search-wonen.funda.io/_msearch/template` | POST | 搜索房源 |
| `listing-search-wonen.funda.io/geo-wonen-alias-prod/_search/template` | POST | 自动补全位置/搜索框文本 |
| `listing-detail-summary.funda.io/api/v1/listing/nl/{globalId}` | GET | 获取轻量级房源摘要 |
| `contacts-flows-bff.funda.io/.../contact-block` | GET | 获取经纪人联系区块 |
| `contacts-bff.funda.io/.../contact-form` | GET | 获取联系表单可用性 |
| `local-listings.funda.io/api/v1/similarlistings` | GET | 获取相似和最近售出的房源 ID |
| `marketinsights.funda.io/v2/localinsights/preview/...` | GET | 获取社区市场洞察 |
| `brokerpresentation-office-pages-bff.funda.io/.../office-page/...` | GET | 获取经纪人资料和房源列表 |
| `reviews-office-pages-bff.funda.io/.../reviews/nl` | GET | 获取经纪人评价汇总 |
| `api.walterliving.com/hunter/lookup` | POST | 获取价格历史数据 |
请求传输、请求头、重试配置以及 TLS 指纹轮换都是内部实现细节。普通用户只需构建 `Funda()` 并调用下面列出的公共方法即可。
## 文档
- [从这里开始](docs/README.md)
- [API 参考](docs/API.md)
- [架构说明](docs/ARCHITECTURE.md)
- [示例](docs/EXAMPLES.md)
- [开发与测试](docs/DEVELOPMENT.md)
## 免责声明
这是一个非官方库，不隶属于、未经 Funda 或其任何关联公司授权、维护、赞助或认可。使用风险自负。
本库仅通过 Funda 未公开的内部 API 访问公开可用的房源数据。使用本库可能违反 Funda 的服务条款。作者不对使用本软件产生的任何后果负责。
本项目仅供个人使用、研究和教育目的。
- 这些 API 是未公开的，可能随时更改或失效，恕不另行通知。
- 请负责任地使用本库，避免过多的请求给 Funda 的基础设施带来负担。
- 数据可能受版权和使用限制的约束。请确保您的使用符合适用的法律。
## 许可证
AGPL-3.0
标签：API客户端, API封装, Funda, JSON API, Python, Python包, TTP, URL抓取, 云资产清单, 代码示例, 价格历史, 住宅搜索, 反爬绕过, 后渗透, 开源, 房产平台, 房产数据, 房产经纪人, 房地产, 房屋 listings, 数据分析, 数据抓取, 数据泄露, 数据获取, 无后门, 无头浏览器, 爬虫替代, 移动端API, 网络信息收集, 网络调试, 自动化, 荷兰, 运行时操纵, 逆向工具, 逆向工程