49图库开发文档开放：只读统计接口的调用说明

2026 年 6 月 6 日，49图库开放开发文档。文档说明 6 个只读统计接口的地址、请求参数、返回字段与错误码，附 curl 与 Python 两种调用示例。接口只返回已公开的历史统计数据，不涉及账户、下载授权或任何投注相关内容。

开放文档的直接原因，是此前的接口靠口口相传。有人从页面源码里找到了请求地址，用的时候不知道频率上限，也不知道参数含义，出问题只能猜。文档缺位时，使用者能依靠的只有试错。

编写时先定边界：只写只读接口，只写公开数据，只写当前版本真实存在的行为。文档不发任何密钥，也不需要注册。所有示例都可以直接复制运行，返回值取自真实响应，敏感字段已剔除。

文档包含哪些内容

文档分六节：概览、认证说明、接口列表、参数详解、错误码、调用示例。概览写清服务地址、数据更新时间与可用范围；认证说明明确写出“无需认证，仅按 IP 限流”，避免使用者到处找密钥。

接口列表逐个给出方法与路径，参数详解标注必填与可选、类型与默认值，错误码覆盖 200、400、404、429、500 五种情况。每种错误都配一句处理建议，例如 429 建议按响应头中的重试秒数退避。

文档带版本号，与站点发布同步更新，页首标注最近修改日期与适用版本。每次接口行为变化都会在变更记录里写明旧行为、新行为与生效日期，旧版本说明保留可查。这样即使使用者几个月后再看，也能知道自己脚本面对的是哪一版行为。

文档最短的写法是把代码贴出来，最长的写法是解释为什么这样设计。两者都要有，比例大概三比一。—— 49图库后端负责人 郭文轩

6 个接口与频率限制

6 个接口分别是：按期号查询单期记录、按区间查询明细、号码频次统计、区间分布统计、尾数结构统计、连号识别。全部为 GET 请求，返回 JSON，单次最多 5,000 期，超出返回 400 并提示拆分区间。

频率限制与页面一致：单 IP 每分钟 60 次，单路径每分钟 20 次。响应头返回剩余配额与重置时间。文档明确说明这项限制会随负载调整，调整前会更新文档并在资讯里说明。

返回结构统一为三层：状态码、数据体、分页信息。数据体中的号码为字符串数组，保留前导零；日期为 YYYY-MM-DD；统计值为数字，不做千分位格式化。分页信息包含当前页、每页条数与总条数，超出上限时返回 400 并提示拆分区间。

文档页的代码块带复制按钮，复制内容不含行号与提示文字，粘贴后可直运行。页面本身不加载任何第三方脚本，示例中的 Python 代码只用标准库，避免使用者为了跑一个示例先装一堆依赖。文档的静态版本也在离线包中提供，断网时可查。

调用示例与常见错误

curl 示例只写一行，参数放在查询串里，返回结果用注释说明字段含义。Python 示例使用标准库，不引入第三方依赖，代码包含超时设置与 429 退避，可以直接放进脚本里跑。两个示例都在文档页内可复制。

最常见的三个错误：把日期当成期号传参、区间跨度超过上限、忽略 429 后立刻重试。文档在错误码一节各配一条反例，写清正确的参数形式与退避写法，比只列错误码更省沟通。

文档明确写出三类不支持的行为：批量抓取全站、绕过频率限制、任何与投注相关的用途。前两项会被限流拦截，第三项不属于本站的服务范围。文档只描述公开历史统计数据的读取方式，不提供账户、下载授权或数据修改能力。

错误码按处理方式分组：400 检查参数格式与区间上限；404 确认期号是否存在；429 按响应头中的重试秒数退避，不要立即重试；500 记录请求时间与参数后反馈。每组都给出一个最小复现示例，使用者对照示例就能判断自己属于哪一类。

文档页顶部有一段三行说明，写清服务地址、数据更新频率与不需要认证这三件事。这三行是刻意放在最前面的，因为反馈里重复率最高的三个问题正好对应这三件事，写在开头能省掉大量来回确认。

写文档时要假设读者只会看一遍。一遍看不懂，他就会去抓页面，然后带着一身问题回来。—— 49图库产品负责人 李承宇

开发文档已放入关于页的说明入口，随版本发布同步更新，每次变更在页首标注日期。文档只覆盖公开统计数据，不提供批量抓取授权，也不涉及任何账户体系。如果示例无法运行或返回与文档不符，请提供请求地址与响应码，我们会在两个工作日内核对。