场景
适用场景
这个接口适合用在什么地方？下面的场景可以帮你判断它是不是你要找的那个。
- 做车组详情页的历史担当时间线。
- 追踪某个车组近期的运用轨迹，判断它常跑哪些线路。
问答
常见问题
接入时最常遇到的疑问，先看看这里能不能解答。
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": [
"meta",
"data"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"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"
],
"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
}
}
}
}
}
}
}
},
"emuCodeMappings": {
"type": "object",
"shape": {
"type": "object"
}
},
"timetableMappings": {
"type": "object",
"shape": {
"type": "object"
}
}
}
}
}
}
}示例响应
{
"ok": true,
"data": {
"emuId": 1500,
"cursor": "",
"limit": 2,
"nextCursor": "20679:1880201",
"items": [
{
"id": 1880202,
"serviceDay": 20679,
"timetableId": 18287,
"trainCode": {
"prefix": "G",
"number": 240
}
},
{
"id": 1880201,
"serviceDay": 20679,
"timetableId": 18287,
"trainCode": {
"prefix": "G",
"number": 237
}
}
],
"emuCodeMappings": {
"1500": "CR400BF-A-5156"
},
"timetableMappings": {
"18287": {
"startStation": "上海虹桥",
"endStation": "成都东",
"startOffset": 32640,
"endOffset": 70500
}
}
},
"error": ""
}400
请求参数不合法：可能是日期格式、游标格式或 limit 不符合要求。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "invalid_param",
"message": "date 必须使用 YYYYMMDD 格式。"
}
}401
请求未携带有效的认证信息，或提供的 API Key 已失效。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "invalid_api_key",
"message": "API Key 无效或已过期。"
}
}403
当前凭证缺少调用该接口所需的 scope。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "forbidden",
"message": "缺少调用该接口所需的权限。"
}
}429
额度不足或请求过于频繁，建议等 Retry-After 提示的时间后再试。
响应头
x-api-remainx-api-costRetry-After
application/jsonobject
响应结构
{
"type": "object",
"required": [
"meta",
"error"
],
"properties": {
"meta": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"remain",
"cost"
],
"properties": {
"remain": {
"type": "integer",
"required": true
},
"cost": {
"type": "integer",
"required": true
},
"retryAfter": {
"type": "integer"
}
}
}
},
"error": {
"type": "object",
"required": true,
"shape": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "string",
"required": true
},
"message": {
"type": "string",
"required": true
}
}
}
}
}
}示例响应
{
"meta": {
"remain": 159,
"cost": 1
},
"error": {
"code": "rate_limited",
"message": "额度不足，请稍后再试。"
}
}