英国商业地产 API 分页采集:出租与出售房源如何保存断点

发布于 2026年10月31日

currentPage 返回 1,不等于“导出任务应该从头开始”。它既不记得上次写入了哪一页,也不会保留当时的筛选条件。英国商业地产 API 分页采集真正要保存的,是查询上下文、已经提交的原始页,以及下一次允许请求的页码。

currentPage 只是本次商业房源查询的页码,不是采集断点

commercial-property-to-rent 与 commercial-property-to-sale 已观察到相同的分页外层:data 数组,以及整数 currentPage、resultsPerPage、totalResultCount。这不表示两个接口的房源对象完全相同,更不表示查询结果被冻结。

把任务分成“待请求、原始页已提交、断点已推进、暂停复核”四种状态。保存的页码必须属于一个确定的出租或出售查询,不能拿出租的第七页接着跑出售,也不能因为进程重启就默认上一页已经落盘。

先固定出租或出售条件,再保存断点上下文

先用 auto-complete 的 location 输入地点文字,检查候选项的 displayName,再把所选 locationIdentifier 传给商业查询的 identifier;不要直接填城市名。出租安全示例使用 REGION^274、page=1、search_radius=0.0,它不是所有英国地区的通用标识。

断点上下文应记录操作名及所有实际发送的筛选项,包括 identifier、property_type、search_radius、sort_by,以及价格、面积上下界。未传的参数也要保持未传,不要恢复时补上新默认值。页码单独推进,平台 key 不参与查询指纹。

价格区间用 min_price、max_price,面积区间用 min_size、max_size 配合 size_unit。面积单位可选 SquareFeet、SquareMetres、Acres、Hectares,不应假设接口自动换算。出租还需核对 price_type:PricePerCalendarMonth 与 PricePerUnit 不能混算,也不能自行把后者解释成年租金或每平方米租金。

如果实际需求是住宅,新房用 new-homes-for-sale,一般待售房源用 property-for-sale;普通租房的 property-to-rent 支持 furnished_type、卧室上下限和预算筛选。留学生租房用 student-property-to-rent,仍须固定 identifier 与 search_radius,不能自行给未标注单位的半径加上“英里”。这些查询另建任务,不并入商业导出。

类似应用的 API 需求可通过联系页面提出,也提供私有化源码部署。

校验 data 与三个整数分页字段,不猜测房源对象结构

先诊断响应,再决定是否写断点:HTTP 2xx 只是传输成功,还要确认 JSON 对象中的 status 为 true。data 应为对象数组;三个分页字段必须是真正的整数,不能把布尔值、数字字符串或缺失值强转成页码。请求页与 currentPage 不一致时立即暂停。

这些是本导出器的入库门槛,不是对所有响应的额外服务承诺。已有证据不足以保证每行都有地址、价格或稳定房源 ID,因此先保存原始对象,不凭猜测抽取 id 去重。平台 key 只从环境变量读取;不要提交到代码库,也不要记录含 key 的完整请求 URL。

先落盘当前页,再推进断点,失败后从哪里恢复

手动执行时,请求地址采用平台入口;这里只展示安全的首请求,不保证返回非空房源:

GET https://api.opendata-api.com/api/project/rightmove/commercial-property-to-rent?key=YOUR_API_KEY&identifier=REGION%5E274&page=1&search_radius=0.0

首次请求前,把 context、nextPage=1、total=null、perPage=null、hashes=[]、done=false 保存到 checkpoint.json。context 包含操作名与固定筛选项,不含 key。以下是接在请求器之后的单页提交函数;只让一个进程写同一任务目录,HTTP 检查在调用前完成。

import hashlib
import json
import os
from pathlib import Path


def durable(path, content):
    tmp = path.with_suffix(path.suffix + ".tmp")
    with tmp.open("wb") as f:
        f.write(content)
        f.flush()
        os.fsync(f.fileno())
    os.replace(tmp, path)
    fd = os.open(path.parent, os.O_RDONLY)
    try:
        os.fsync(fd)
    finally:
        os.close(fd)


def commit(raw, saved, context, directory):
    if saved["context"] != context or saved["done"]:
        raise RuntimeError("Context changed or run already finished")
    r = json.loads(raw)
    if not isinstance(r, dict) or r.get("status") is not True:
        raise RuntimeError("Business response needs review")
    rows = r.get("data")
    fields = ("currentPage", "resultsPerPage", "totalResultCount")
    if not isinstance(rows, list) or any(not isinstance(x, dict) for x in rows):
        raise RuntimeError("Unexpected data shape")
    if any(type(r.get(k)) is not int for k in fields):
        raise RuntimeError("Invalid pagination types")
    page, size, total = (r[k] for k in fields)
    if page != saved["nextPage"] or page < 1 or size < 1 or total < 0:
        raise RuntimeError("Unexpected pagination values")
    if saved["total"] not in (None, total) or saved["perPage"] not in (None, size):
        raise RuntimeError("Pagination baseline moved")
    digest = hashlib.sha256(json.dumps(
        rows, sort_keys=True, separators=(",", ":"), ensure_ascii=False
    ).encode()).hexdigest()
    if not rows or digest in saved["hashes"]:
        raise RuntimeError("Empty or repeated batch; stop for review")
    directory = Path(directory)
    durable(directory / f"page-{page:06d}.json", raw)
    updated = {**saved, "nextPage": page + 1, "total": total, "perPage": size,
               "hashes": saved["hashes"] + [digest], "done": page * size >= total}
    durable(directory / "checkpoint.json", json.dumps(updated).encode())
    return updated

directory 须预先创建;将原始响应字节传入 raw。页文件写入、同步并原子替换后,才允许写新断点。若页已保存而断点没更新,重启先读取对应页文件重新校验并提交,不重新请求它;若连页文件都未保存,就从断点指向的页重试。不要根据临时文件或日志猜进度。网络超时、HTTP 错误与校验异常均不得推进页码,捕获异常后暂停调度,避免无限重试。

遇到重复页、空批次或总数变化时暂停并复核

响应页码重复或跳页、非空批次指纹重复、空数组、总数变化、每页容量变化,都应保留既有文件并进入复核。空数组可以是正常无匹配,但在这个导出器里仍需人工确认停止原因,不能伪装成已经导完。

指纹只识别内容和顺序相同的整批重复,不能证明没有跨页重叠。总数稳定且 page * resultsPerPage >= totalResultCount 时,代码只标记到达本次观察到的页边界;不据此认定唯一房源数量。复核后若要改筛选或接受新基线,另开任务目录,保留旧任务,而不是悄悄接续。

成交价接口返回 meta,不能套用商业房源分页循环

house-prices-sold-house-prices 已观察到 data 和 meta,根级三个分页字段可以缺失。不要填零补齐,也不要臆造 meta.totalPages。先检查实际 meta 与该操作文档,单独确定继续条件;未确定时只保存当前页,不自动递增。

它的地点来自 house-prices-auto-complete,需要配套的 identifier 和 type。商业挂牌报价与历史成交价属于不同口径,既不能直接混算,也没有证据支持逐套房产精确关联或自动估值。

导出报告写明已观察范围,不声称覆盖整个英国市场

报告保留操作名、筛选上下文、开始与结束时间、已提交页号、累计原始行数、各页分页值及暂停原因。明确区分“到达返回总数的页边界”和“中途暂停”,不要把累计行数写成独立物业数。

接口成功只说明本次请求执行成功;导出还受房源增删、排序变化、重复记录及地区范围限制。它不是固定时点的英国全市场快照,也不证明仍可租售、法定用途或价格可比性。对选址团队和营销研究人员,能复核来源与中断位置的有限样本,比没有证据的“全量英国房源”更可靠。