场景
适用场景
这个接口适合用在什么地方？下面的场景可以帮你判断它是不是你要找的那个。
- 按天拉取全量担当数据，建立自己的车次-车组对应关系表。
- 做一个“某天所有车次都用了哪些车组”的查询页面。
问答
常见问题
接入时最常遇到的疑问，先看看这里能不能解答。
items 里的 emuId 和 trainCode 怎么理解？
为了减少重复数据，记录里存的是车组 ID（emuId）和结构化的车次号（trainCode），对应的车组编号和时刻表摘要分别放在 emuCodeMappings 与 timetableMappings 里，按 ID 查表即可。
serviceDay 为什么是数字而不是日期字符串？
serviceDay 表示服务日期，是按上海时间自 1970-01-01 起的天数（epoch day），例如 2026-08-14 对应 20679。它只是内部表示，需要展示日期时再换算即可。
扣费
扣费规则
items 表示本次响应实际返回的记录条数，按记录数计算后再应用最低扣费。
按本页返回条数计费，0.10 额度/条，向上取整，最低扣费额度为 1
实际扣费以响应头 x-api-cost 为准；请求失败时也可能触发最低扣费。
请求说明
参数
查询参数
datestring 必填
要读取的日期，格式为 YYYYMMDD，例如 20260814。
示例：20260814
limitinteger
每一页最多返回多少条记录。不传时使用默认值 20；超过服务端配置上限（当前为 200）时会被自动截断。
示例：20
cursorstring
分页游标，格式为 serviceDay:id（例如 20679:1894995）。第一页不需要传，翻页时直接复用上一页响应里的 nextCursor。serviceDay 是按上海时间自 1970-01-01 起的天数（epoch day），不是日期字符串。
示例：20679:1894995
响应说明
状态码与响应格式
200
一页每日记录数据。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "true",
"required": true,
"enum": [
true
]
},
"data": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"serviceDay",
"cursor",
"limit",
"nextCursor",
"items"
],
"properties": {
"serviceDay": {
"type": "integer",
"required": true
},
"cursor": {
"type": "string",
"required": true
},
"limit": {
"type": "integer",
"required": true
},
"nextCursor": {
"type": "string",
"required": true
},
"items": {
"type": "array<object>",
"required": true,
"shape": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"serviceDay",
"emuId",
"status"
],
"properties": {
"id": {
"type": "integer",
"required": true
},
"serviceDay": {
"type": "integer",
"required": true
},
"timetableId": {
"type": "integer"
},
"emuId": {
"type": "integer",
"required": true
},
"trainCode": {
"type": "object",
"shape": {
"type": "object",
"required": [
"prefix",
"number"
],
"properties": {
"prefix": {
"type": "string",
"required": true
},
"number": {
"type": "integer",
"required": true
}
}
}
},
"status": {
"type": "integer",
"required": true
}
}
}
}
},
"emuCodeMappings": {
"type": "object",
"shape": {
"type": "object"
}
},
"timetableMappings": {
"type": "object",
"shape": {
"type": "object"
}
}
}
}
},
"error": {
"type": "",
"required": true,
"enum": [
""
]
}
}
}示例响应
{
"ok": true,
"data": {
"serviceDay": 20679,
"cursor": "",
"limit": 2,
"nextCursor": "20679:1894995",
"items": [
{
"id": 1894996,
"serviceDay": 20679,
"timetableId": 1075,
"emuId": 3378,
"trainCode": {
"prefix": "G",
"number": 7309
},
"status": 3
},
{
"id": 1894995,
"serviceDay": 20679,
"timetableId": 1075,
"emuId": 3522,
"trainCode": {
"prefix": "G",
"number": 7309
},
"status": 3
}
],
"emuCodeMappings": {
"3378": "CRH380B-3602",
"3522": "CRH380B-3752"
},
"timetableMappings": {
"1075": {
"startStation": "上海南",
"endStation": "杭州东",
"startOffset": 82500,
"endOffset": 85320
}
}
},
"error": ""
}400
date 查询参数不是有效的 YYYYMMDD 日期。；limit 查询参数不是正整数。；cursor 查询参数格式无效。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}date 查询参数不是有效的 YYYYMMDD 日期。
{
"ok": false,
"data": "date 必须是 YYYYMMDD",
"error": "invalid_param"
}limit 查询参数不是正整数。
{
"ok": false,
"data": "limit 必须是正整数",
"error": "invalid_param"
}cursor 查询参数格式无效。
{
"ok": false,
"data": "cursor 必须是 \"serviceDay:id\" 格式",
"error": "invalid_param"
}401
请求未携带有效的认证信息，或提供的 API Key 已失效。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "API Key 无效或已过期",
"error": "invalid_api_key"
}403
账号已被封禁。；当前凭证缺少调用该接口所需的 scope。；当前身份的额度上限低于接口最低调用成本。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}账号已被封禁。
{
"ok": false,
"data": "账号已被封禁",
"error": "account_banned"
}当前凭证缺少调用该接口所需的 scope。
{
"ok": false,
"data": "当前 API Key 缺乏访问该接口的权限",
"error": "forbidden_scope"
}当前身份的额度上限低于接口最低调用成本。
{
"ok": false,
"data": "当前身份额度上限不足，无法调用该接口",
"error": "cost_exceeds_quota_limit"
}406
Accept 请求头不支持 JSON 响应。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "Accept 不支持 application/json 或 application/x-protobuf",
"error": "not_acceptable"
}429
额度不足或请求过于频繁，建议等 Retry-After 提示的时间后再试。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "额度不足，请稍后再试",
"error": "quota_exceeded"
}500
服务内部错误或响应编码失败。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"ok",
"data",
"error"
],
"properties": {
"ok": {
"type": "false",
"required": true,
"enum": [
false
]
},
"data": {
"type": "string",
"required": true
},
"error": {
"type": "string",
"required": true
}
}
}示例响应
{
"ok": false,
"data": "服务内部错误，请稍后再试",
"error": "internal_error"
}