数据访问与 API

站上的表格都是由下面这些 JSON 接口渲染出来的，所以你看得见的东西都能直接抓。读取接口不需要密钥、不用注册，也没有限流。我们只有两个请求：注明出处，以及别太用力——把结果缓存起来，不要比数据本身的更新频率还快地轮询。

一句话版本

• GET /api/rankings —— 某个筛选组合（时段、地区、系统、来源）下的排行榜。
• GET /api/results —— 全部公开测试记录，分页，最新在前。
• GET /api/results/{id} —— 单条记录，含完整明细。
• GET /api/provider/{name} —— 单个工具：中位数、分组统计和 90 天时间线。
• GET /api/observatory/* —— 外部观测站（OONI、Tor Metrics、Cloudflare Radar、IODA、GreatFire）按国家的数据。
• GET /api/intel/stats —— 指纹实验室的 IP 情报汇总统计。
• GET /api/stats —— 站点总量、最近一次同步和首页脉冲条的数据。

所有响应都是 application/json; charset=utf-8，形如 { "ok": true, ... }；出错时返回 { "ok": false, "error": "…" }，状态码 400 或 404。接口路径不带语言前缀：/api/rankings 对所有语言都一样。

通用参数

好几个接口共用同一组筛选参数，拼写必须完全一致（小写）。

参数	取值	默认
period	today（24 小时）、week、month、60days、3months（90 天）、all	排行榜为 60days，工具页为 all
location	mainland china、russia、iran、turkmenistan、other、all	all
os	windows、android、macos、ios、linux、chromeos、all	all
source	greatfire（导入）、breakhub（本站实测）、all	all

中国大陆的键里有一个空格，写在 URL 里是 mainland%20china。速度单位是字节/秒（除以 125 000 得到 Mbit/s），延迟是毫秒，稳定性是图片加载成功的百分比。时间戳是 UTC 的 ISO 8601。

/api/rankings

返回和首页一模一样的排行榜，包括如何阅读排行榜里说的入榜规则。

curl 'https://breakhub.org/api/rankings?period=60days&location=russia&os=android'

额外参数：servicesOnly（1/0，默认 1：把自建协议排除在排名池之外）和 minTests（1–50，默认 5）。未知或格式错误的值会回退到默认值，而不是报错。

响应里有 filters、counts（每个地区和系统标签下有多少工具达标）、tools（先是入榜的，再是未入榜的；每项含 count、avgSpeed、avgLatency、avgStability、ranking、score、providerType、pricingModel 和 sources 分布）、locationMedian（该地区全部测试的中位数）以及 upstream（GreatFire 最近一次快照，用我们的算法重新排名后的结果，若有）。缓存 60 秒。

/api/results

原始记录，包括没有使用任何工具的测试（tool: "None"）。被隐藏的行永远不会返回。

curl 'https://breakhub.org/api/results?tool=Shadowrocket&location=mainland%20china&page=1&limit=100'

参数：上面的通用筛选（这里无效值会返回 400）、tool（精确名称）、ipCountry（两位国家码）、page（从 1 起）和 limit（1–200，默认 50）。每行包含 id、source、createdAt、location、tool、toolVersion、os、browser、ipCountry、speedAvg、latencyMedian、stabilityPct、reachOk/reachTotal 以及一个 streaming 估算。用 page 翻页，total 告诉你什么时候翻完。缓存 30 秒。

/api/results/{id} 返回单行加上 detail 对象：每次测速的样本和 URL、各域名的延迟、图片加载和可达性探测。从 GreatFire 导入的记录（gf_ 开头的 id）还带 upstreamUrl，指向原始页面。

/api/provider/{name}

工具页上的全部内容。名称要做 URL 编码；period 默认 all，stat 可以是 median（默认）或 mean。

curl 'https://breakhub.org/api/provider/Shadowrocket?period=3months'

响应里有 overall（次数、中位数、最小/最大值）、byLocation、byOs、byVersion 三组分组统计、最近 90 天按日的 timeline、最新 20 条 recent 记录，以及 upstream 链接。未知工具返回 404。缓存 60 秒。

/api/observatory/*

来自其他项目的公开测量，我们存了一份，这样上游慢或被封时页面照常可用。每个路由都接受 country（CN、RU、IR、TM）或 location（排行榜的地区键），大多数还接受 days。

路由	days 默认 / 上限	返回什么
/api/observatory/summary	—	断网状态、7 天 OONI 异常、Tor 桥接用户、连接质量
/api/observatory/reach	14 / 90	OONI 网页连通性：各域名逐日的异常率
/api/observatory/tools	30 / 90	OONI 翻墙工具测试（Tor、Snowflake、Psiphon……）逐日结果
/api/observatory/tor	90 / 366	Tor Metrics 的桥接与中继用户数，按传输方式
/api/observatory/quality	28 / 90	Cloudflare Radar 的带宽、延迟和 DNS 耗时
/api/observatory/outages	30 / 90	IODA 和 Radar 记录的断网事件
/api/observatory/greatfire	—	GreatFire 的被封域名列表（仅中国）
/api/observatory/status	—	每个来源最近一次同步时间及错误

curl 'https://breakhub.org/api/observatory/outages?country=IR&days=60'

这些接口缓存 10 分钟，背后的同步每六小时跑一次。每个来源有自己的条款，观测台页面在每个面板旁边都写了出处；复用这些数字时请注明原项目。

/api/intel/stats

指纹实验室里 IP 情报查询的汇总：出现最多的网络及其 VPN / 代理 / Tor / 托管的比例、按浏览器分的 TLS 指纹族，以及 DNS 泄漏测试见到的解析器网段。没有参数；一切都是聚合结果（前 50 个网络，数量太少的行不显示），不暴露任何单次查询。缓存 5 分钟。

新鲜度与缓存

GreatFire 的导入每小时一次，本站实测的记录即时出现，观测站每六小时刷新。/api/stats 里有 lastSync，能看出导入数据有多旧。每个接口都设置了 Cache-Control，请遵守；如果你自己留一份副本，每小时刷新一次就够了，数据本来也只以这个频率变化。带上一个写有联系方式的 User-Agent，出问题时我们能找到你。

这些指南也有 Atom 订阅：/zh/kb/feed.xml（换语言码即可得到其他语言）。

署名与许可

这些接口里流过两类数据，条款不同。

本站实测的测试（source: "breakhub"）以知识共享 署名 4.0发布。你可以复制、转发、在其之上再创作，商用也可以，只要注明"BreakHub（breakhub.org）"，并在方便的地方给出链接。建议引用格式：BreakHub，“网络访问工具性能观测”，breakhub.org，检索于 YYYY-MM-DD。

从 GreatFire 导入的行（source: "greatfire"，id 以 gf_ 开头）仍然是 GreatFire 的数据。我们依照翻墙中心的公开条款转发；复用时请把来源标为 GreatFire Circumvention Central 而不是我们，并到他们的网站核对最新条款。每条导入记录的 upstreamUrl 指向原始页面。

观测站路由转发的 OONI、Tor Metrics、Cloudflare Radar、IODA 和 GreatFire 数据各自遵循原项目的许可。代码、排名算法和这些指南的文字是我们的；大段转载指南前请先打个招呼。

希望你不要做的事

JSON 明明在那里却去抓 HTML 页面；用 limit=200 在死循环里猛刷 /api/results；把导入的 GreatFire 数据说成是我们测的。今天这些都没有靠密钥来强制——靠的是这个站很小，而我们想让它一直开放下去。