接口约定
调用前先看这里
在调用下面的接口之前，先花一分钟了解这些约定，可以少踩很多坑。
基础路径
所有 v2 接口都以 /api/v2 作为基础路径，页面里展示的接口路径会自动拼接上前缀。
鉴权方式
大部分查询接口支持匿名访问；需要读取账户信息或更高额度的接口，使用 API Key 或登录会话。API Key 通过 authorization 请求头以 Bearer 方式传递，在用户页的“开发”页即可签发。第三方应用接入登录流程请看 OAuth 文档。
额度与响应头
游客默认上限 300 点，登录用户默认上限 2000 点，同一用户的所有 API Key 共享同一份额度；额度每 60 秒恢复 10 点。每次响应的 meta 字段和响应头（x-api-remain、x-api-cost、Retry-After）都会带上剩余额度、本次扣费和重试等待时间。
响应结构
成功时返回 meta + data，失败时返回 meta + error（包含 code 和 message）。支持分页的接口还会返回 cursor、limit 和 nextCursor。
{
"meta": {
"remain": 199,
"cost": 1
},
"data": {}
}{
"meta": {
"remain": 199,
"cost": 1
},
"error": {
"code": "invalid_param",
"message": "date 必须使用 YYYYMMDD 格式。"
}
}字段命名
JSON 字段统一使用小驼峰命名，例如 serviceDayStart。
可选字段会省略
没有数据的可选字段会直接不返回，而不是返回空值；普通字段则总是返回默认值（0、空字符串、false 或空数组）。
64 位整数按数字返回
时间戳等 64 位整数字段会以数字形式返回。日常使用没有问题，但如果数值超过 2^53，需要注意精度。
分页方式
分页接口用 cursor 翻页：第一页不传 cursor，之后把上一页的 nextCursor 原样传回。limit 不传时默认 20，上限 200。
原始文件下载
交路图和日导出文件支持 binary=true 直接返回原始内容（PNG/PDF/CSV），否则返回 JSON 包装结构。
如果你想直接用程序读取这份文档（例如接入 AI 工具或自动生成客户端），可以下载 openapi.json ，它是与页面同源的 OpenAPI 3.1 规范文件。
身份
与当前登录会话、API Key 和额度状态相关的接口。
记录
按日期分页读取车次与车组的担当记录。
时刻表
读取车次当前时刻表、历史时刻表、车站时刻表，以及交路图图片。
历史
按车次号或车组号查询历史担当记录。
配属
查询动车组的配属基础信息。
导出
列出并下载按日生成的 CSV 导出文件。