UK Property Data

Property Shared

一站式英国房产数据包。可获取土地注册处的销售数据、EPC 证书、Rightmove 房源、租金收益率、印花税计算、规划门户链接以及 Companies House 记录。

可作为 Python 库、CLI、HTTP API 或 MCP 服务使用。

可获取的数据

数据来源	返回内容
Land Registry PPD	成交价、日期、房产类型、区域可比数据（含中位数／百分位数）
EPC (GOV.UK)	能效评级、建筑面积、供暖成本。仅限英格兰和威尔士。证书查询和摘要搜索——详见下方 EPC 说明
Rightmove	当前房源（出售＋出租）、价格、中介、房源详情
Yield Analysis	结合 PPD 销售数据与 Rightmove 租赁数据计算毛收益率
Stamp Duty	根据 2025 年 4 月税档计算 SDLT，含 BTL 附加税和 FTB 减免
Block Analyzer	按楼栋归类公寓销售记录，以发现投资者退出
Planning	查询当地市政规划门户（99 个已验证市政区，仅支持 stdio）
Companies House	按名称或编号搜索和查询公司

技能与插件

房产和法律工具包即将推出。如果你在英国房产投资、英国房地产中介、房产及过户方面有实践经验或专业知识，并愿意协助完善这些内容，请联系我们。[email protected]

用作 MCP 服务

无需安装——将 URL 粘贴到 MCP 客户端配置中即可使用。

Claude Code、Cursor 及任何 MCP 客户端：

{
  "mcpServers": {
    "property-shared": {
      "type": "http",
      "url": "https://property-shared.fly.dev/mcp"
    }
  }
}

安装

pip install property-shared

# or with uv
uv add property-shared

附加选项：[cli] 用于 CLI，[api] 用于 HTTP 服务。

pip install property-shared[cli]
# or
uv add property-shared --extra cli

用作 Python 库

from property_core import PPDService, calculate_yield, calculate_stamp_duty

# Get comparable sales for a postcode
comps = PPDService().comps("SW1A 1AA", months=24, property_type="F")
print(f"Median flat price: {comps.median:,}")

# Calculate rental yield
import asyncio
result = asyncio.run(calculate_yield("NG1 1AA", property_type="F"))
print(f"Gross yield: {result.gross_yield_pct}%")

# Stamp duty
sdlt = calculate_stamp_duty(250000, additional_property=True)
print(f"SDLT: {sdlt.total_sdlt:,.0f} ({sdlt.effective_rate}%)")

所有模型都可在顶层使用：

from property_core import (
    PPDTransaction, PPDCompsResponse, EPCData,
    RightmoveListing, RightmoveListingDetail,
    PropertyReport, YieldAnalysis, RentalAnalysis,
    BlockAnalysisResponse, CompanyRecord, StampDutyResult,
)

解读辅助函数（核心功能返回数值，具体标签由你决定）：

from property_core import classify_yield, classify_data_quality, generate_insights

用作 CLI

pip install property-shared[cli]  # or: uv add property-shared --extra cli

# Comparable sales
property-cli ppd comps "SW1A 1AA" --months 24 --property-type F

# Rental yield
property-cli analysis yield "NG1 1AA" --property-type F

# Stamp duty
property-cli calc stamp-duty 300000

# Rightmove search (with sort)
property-cli rightmove search-url "NG1 1AA" --sort-by most_reduced

# Full property report
property-cli report generate "10 Downing Street, SW1A 2AA" --property-type F

在任何命令中添加 --api-url http://localhost:8000，即可通过 HTTP API 路由，而不是直接调用核心功能。

用作 HTTP API

pip install property-shared[api]  # or: uv add property-shared --extra api
property-api  # starts on port 8000

交互式文档位于 http://localhost:8000/docs。

主要端点：

• GET /v1/ppd/comps?postcode=SW1A+1AA&property_type=F&enrich_epc=true
• GET /v1/analysis/yield?postcode=NG1+1AA&property_type=F
• GET /v1/analysis/rental?postcode=NG1+1AA&purchase_price=200000
• GET /v1/rightmove/search-url?postcode=NG1+1AA&sort_by=newest
• GET /v1/calculators/stamp-duty?price=300000&additional_property=true
• POST /v1/property/report，附带 { "address": "10 Downing Street, SW1A 2AA" }

完整端点列表见 USER_GUIDE.md。

EPC 说明（v1.14.0）

EPC 服务已迁移至 GOV.UK Bearer API。请设置 EPC_API_TOKEN；旧的 EPC_API_EMAIL/EPC_API_KEY 组合用于向已停用的主机进行身份验证，不受支持，也不能作为备用方案。

新上游支持和不支持的功能：

• 按证书编号查询证书 — 一次请求即可获取完整详情。
• 按邮政编码搜索摘要 — 返回地址、UPRN（通常缺失）、能效等级、注册日期和架构类型。它不会返回能效评分、建筑面积或物业类型；这些信息仅存在于完整证书中。
• 邮政编码用于选择区域，而非物业。 要识别某个物业，必须提供 UPRN，或提供与证书完全匹配的地址（大小写、标点以及开头的 Flat/Apartment 标识除外）。任何更宽泛的条件——没有地址、没有匹配项或存在多个匹配项——都会被拒绝，而不是根据最佳猜测来确定。CLI 和 REST 接口见 USER_GUIDE.md。
• 区域统计数据仅限记录数，以及在有界响应包含所有匹配摘要时的能效等级分布。物业类型细分和建筑面积统计会报告为 None，表示不可用，而非零；因为生成这些数据意味着要为每份证书各发送一次请求。
• 覆盖范围为英格兰和威尔士。 苏格兰、北爱尔兰和海峡群岛会返回“未找到证书”：这是覆盖范围的边界，并不代表物业本身的情况。
• 分页结果不是稳定快照。 响应包含 complete、duplicates_removed 和 unusable_rows；任何操作都不会声称已完整获取某个区域的全部数据。
• 地址匹配存在歧义时会拒绝请求，而不是随意选择邻近证书。

不支持 search_all_by_postcode() — 请使用 search_summaries() 查找候选项，然后使用 get_certificate() 获取所需的那份证书。

环境变量

在仓库根目录创建 .env 文件（该文件已被 git 忽略），并填写所需变量。

请完全省略可选变量，不要将其赋为空值。 KEY= 会设置空字符串，这与未设置变量不同：os.getenv("KEY", "default") 会返回 ""，因此不会应用默认值。EPC 实时 测试就遇到了这个问题，向上游发送了空邮政编码。

关键变量：

变量	用途	说明
EPC_API_TOKEN	EPC 查询	从 GOV.UK EPC data 获取 Bearer 令牌
EPC_API_EMAIL	(已弃用)	服务已停用；仅会被解析以引发配置错误
EPC_API_KEY	(已弃用)	服务已停用；不受支持，也不能作为备用方案
COMPANIES_HOUSE_API_KEY	公司搜索	从 Companies House 免费获取密钥
RIGHTMOVE_DELAY_SECONDS	否（默认 0.6s）	Rightmove 抓取的速率限制延迟
OPENAI_API_KEY	规划信息抓取工具	使用视觉引导的规划门户抓取工具

Land Registry PPD 和 Rightmove 无需凭据即可使用。

开发

# Install dependencies (dev tooling installs by default via [dependency-groups])
uv sync

# Run API with reload
uv run --extra api uvicorn app.main:app --reload

# Full validation (lockfile check, pre-commit, all extras, full suite) —
# same entrypoint CI and the release gate use
./scripts/validate.sh

# + live integration tests (real network calls)
RUN_LIVE_TESTS=1 ./scripts/validate.sh

已部署至 https://property-shared.fly.dev，API 文档位于 /docs，MCP 端点位于 /mcp。