文档

API 文档

这套文档由仓库内维护的 OpenAPI 元数据驱动，覆盖鉴权、历史查询、时刻表和每日数据导出接口。

总览私有部署数据抓取流程OAuth 文档API 文档

基础路径

所有 API 接口都以

/api/v1

作为基础路径。

鉴权方式

除鉴权接口和每日数据导出外，其他接口默认都支持匿名访问，也支持使用 API Key 访问。请打开用户页并切换到“开发”页，点击“签发”按钮获取您的 API Key。

API Key 请求头：authorization

如果你要让第三方应用直接接入用户登录流程，请阅读 OAuth 文档 。

额度响应头

每次响应都可能通过响应头返回剩余额度、请求耗额和重试等待时间。 请注意的是，由于大部分查询接口都使用了 Cloudflare 的缓存层，具体配额使用情况请以鉴权接口返回的结果为准。

x-api-remain

x-api-cost

Retry-After

访问额度

游客默认可用额度上限为 160 点，登录用户默认可用额度上限为 2000 点。同一用户下签发的所有 API Key 都共享同一份用户级额度，切换 Key 不会额外增加额度。额度会按配置的恢复周期自动补充，默认每 300 秒恢复 10 点，补充后不会超过当前用户上限。如果默认额度不够，你可以在反馈里说明需求，向管理员申请更多额度。

响应约定

统一响应结构

成功的 JSON 响应统一使用 ok、data、error 这层包装；支持分页的查询接口还会额外使用 limit 和 cursor。 

{
    "ok": true,
    "data": {},
    "error": ""
}

历史

查询车次和车组的担当历史。

get/api/v1/history/emu/{emuCode}

返回单个车组的历史担当记录

返回单个车组的历史担当记录。

可匿名访问api.history.emu.read

扣费规则：按本页返回条数计费，0.10 额度/条，向上取整，最低扣费额度为 1

get/api/v1/history/train/{trainCode}

返回单个车次的历史担当记录

返回单个车次的历史担当记录。

可匿名访问api.history.train.read

扣费规则：按本页返回条数计费，0.10 额度/条，向上取整，最低扣费额度为 1

导出

列出并下载已生成的每日数据导出文件。

get/api/v1/exports/daily/{date}

读取单日导出文件

读取某日车次车底对应关系导出文件。

可匿名访问api.exports.daily.read

扣费规则：固定 400 点额度/次

get/api/v1/exports/daily

列出可用的日导出文件

按年和月列出已生成的日导出文件。

可匿名访问api.exports.daily.read

扣费规则：固定 10 点额度/次

时刻表

读取当前日期下的完整车次时刻表。

get/api/v1/timetable/station/{stationName}

按车站读取当日站内时刻表

返回指定车站的计划车次列表，按列车到站时间升序排序。

可匿名访问api.timetable.station.read

扣费规则：按本页返回条数计费，0.10 额度/条，向上取整，最低扣费额度为 1

get/api/v1/timetable/train/{trainCode}/circulation/image

获取交路运行图图片

根据交路表和首末站坐标生成交路运行图

可匿名访问api.timetable.train.circulation.image.read

扣费规则：缓存命中 2 点/次，缓存未命中 20 点/次，失败 2 点/次

get/api/v1/timetable/train/{trainCode}/current

按车次读取当前完整时刻表

返回该车次的时刻表，包括经停站、当前站车次、检票口信息、参考车型和交路信息。

可匿名访问api.timetable.train.current.read

扣费规则：固定 1 点额度/次

get/api/v1/timetable/train/{trainCode}/history

按车次分页读取历史时刻表清单

返回指定车次的历史时刻表覆盖范围列表。

可匿名访问api.timetable.train.history.read

扣费规则：按本页返回条数计费，0.10 额度/条，向上取整，最低扣费额度为 1

get/api/v1/timetable/train/{trainCode}/history/{historyId}

读取车次历史时刻表内容

读取时刻表内容。

可匿名访问api.timetable.train.history.read

扣费规则：固定 1 点额度/次

记录

分页读取每日运行记录。

get/api/v1/records/daily

分页读取每日记录

读取该日的车次车组担当记录。

可匿名访问api.records.daily.read

扣费规则：按本页返回条数计费，0.10 额度/条，向上取整，最低扣费额度为 1

身份

查看当前鉴权会话的信息。

get/api/v1/auth/me

读取当前鉴权会话

返回当前用户、正在使用的 API Key 摘要以及当前额度桶状态。

api.auth.me.read

扣费规则：固定 1 点额度/次