场景
适用场景
这个接口适合用在什么地方？下面的场景可以帮你判断它是不是你要找的那个。
- 做车组详情页的历史担当时间线。
- 追踪某个车组近期的运用轨迹，判断它常跑哪些线路。
问答
常见问题
接入时最常遇到的疑问，先看看这里能不能解答。
items 里的 trainCode 为什么是对象？
v2 统一用 { prefix, number } 表示结构化车次号。需要展示时拼成字符串即可，例如 prefix 为 "G"、number 为 1824 时就是 G1824。
为什么会出现同一服务日有多条记录？
同一车组一天可能担当多趟车次，每趟车都会产生一条记录，所以同一天出现多条是正常的。
扣费
扣费规则
items 表示本次响应实际返回的记录条数，按记录数计算后再应用最低扣费。
按本页返回条数计费，0.04 额度/条，向上取整，最低扣费额度为 1
实际扣费以响应头 x-api-cost 为准；请求失败时也可能触发最低扣费。
请求说明
参数
路径参数
emuCodestring 必填
要查询的车组编号，例如 CR400AF-C-2214。车组编号区分大小写，请按页面展示的格式填写。
示例：CR400AF-C-2214
查询参数
startinteger
起始时间戳，单位是秒，包含边界。留空表示从最早记录开始。
示例：1786636800
endinteger
结束时间戳，单位是秒，包含边界。留空表示读到最新记录。
示例：1786723200
limitinteger
每一页最多返回多少条记录。不传时使用默认值 20；超过服务端配置上限（当前为 200）时会被自动截断。
示例：20
cursorstring
分页游标，格式为 serviceDay:id（例如 20679:1880201）。第一页不需要传，翻页时直接复用上一页响应里的 nextCursor。serviceDay 是按上海时间自 1970-01-01 起的天数（epoch day），不是日期字符串。
示例：20679:1880201
响应说明
状态码与响应格式
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": [
"emuId",
"cursor",
"limit",
"nextCursor",
"items"
],
"properties": {
"emuId": {
"type": "integer",
"required": true
},
"start": {
"type": "integer"
},
"end": {
"type": "integer"
},
"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",
"status"
],
"properties": {
"id": {
"type": "integer",
"required": true
},
"serviceDay": {
"type": "integer",
"required": true
},
"timetableId": {
"type": "integer"
},
"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": {
"emuId": 1500,
"cursor": "",
"limit": 2,
"nextCursor": "20692:2091894",
"items": [
{
"id": 2110390,
"serviceDay": 20693,
"timetableId": 1137,
"trainCode": {
"prefix": "G",
"number": 7381
},
"status": 1
},
{
"id": 2091894,
"serviceDay": 20692,
"timetableId": 18285,
"trainCode": {
"prefix": "G",
"number": 221
},
"status": 1
}
],
"emuCodeMappings": {
"1500": "CR400BF-A-5156"
},
"timetableMappings": {
"1137": {
"startStation": "上海虹桥",
"endStation": "江山",
"startOffset": 69000,
"endOffset": 79140
},
"18285": {
"startStation": "张家界西",
"endStation": "上海虹桥",
"startOffset": 52740,
"endOffset": 79020
}
}
},
"error": ""
}400
emuCode 为空，或 start、end、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
}
}
}示例响应
{
"ok": false,
"data": "start 必须是秒级时间戳",
"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"
}404
未找到指定的动车组。
响应头
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": "not_found"
}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"
}