场景
适用场景
这个接口适合用在什么地方？下面的场景可以帮你判断它是不是你要找的那个。
- 按天拉取全量担当数据，建立自己的车次-车组对应关系表。
- 做一个“某天所有车次都用了哪些车组”的查询页面。
问答
常见问题
接入时最常遇到的疑问，先看看这里能不能解答。
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": [
"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": [
"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"
],
"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
}
}
}
}
}
}
}
},
"emuCodeMappings": {
"type": "object",
"shape": {
"type": "object"
}
},
"timetableMappings": {
"type": "object",
"shape": {
"type": "object"
}
}
}
}
}
}
}示例响应
{
"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
}
},
{
"id": 1894995,
"serviceDay": 20679,
"timetableId": 1075,
"emuId": 3522,
"trainCode": {
"prefix": "G",
"number": 7309
}
}
],
"emuCodeMappings": {
"3378": "CRH380B-3602",
"3522": "CRH380B-3752"
},
"timetableMappings": {
"1075": {
"startStation": "上海南",
"endStation": "杭州东",
"startOffset": 82500,
"endOffset": 85320
}
}
},
"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": "额度不足，请稍后再试。"
}
}