场景
适用场景
这个接口适合用在什么地方？下面的场景可以帮你判断它是不是你要找的那个。
- 展示某车次历史上使用过哪些时刻表，以及每份时刻表的生效日期范围。
- 把某一天的历史时刻表内容（如经停站）拉出来做对比或归档。
问答
常见问题
接入时最常遇到的疑问，先看看这里能不能解答。
items 里的 serviceDayStart 和 serviceDayEndExclusive 是什么意思？
它们表示这份时刻表的生效区间：从 serviceDayStart 当天开始，到 serviceDayEndExclusive 当天之前结束，即结束日期不包含在区间内。这两个值都是按上海时间自 1970-01-01 起的天数（epoch day），例如 20575 对应 2026-05-02。
为什么历史详情没有单独的接口了？
v2 把历史时刻表的内容直接放在 timetableMappings 里，与覆盖范围一起返回。mapping 的 key 就是 items 里的 timetableId，取出来后就是完整内容。
扣费
扣费规则
items 表示本次响应实际返回的记录条数，按记录数计算后再应用最低扣费。
按本页返回条数计费，0.20 额度/条，向上取整，最低扣费额度为 1
实际扣费以响应头 x-api-cost 为准；请求失败时也可能触发最低扣费。
请求说明
参数
路径参数
trainCodestring 必填
要查询的车次号，例如 G2492、D2212 或 C2001。字母大小写都可以，服务端会做标准化处理。
示例：G2492
响应说明
状态码与响应格式
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": [
"items"
],
"properties": {
"trainCode": {
"type": "object",
"shape": {
"type": "object",
"required": [
"prefix",
"number"
],
"properties": {
"prefix": {
"type": "string",
"required": true
},
"number": {
"type": "integer",
"required": true
}
}
}
},
"items": {
"type": "array<object>",
"required": true,
"shape": {
"type": "array",
"items": {
"type": "object",
"required": [
"coverageId",
"timetableId",
"serviceDayStart",
"serviceDayEndExclusive"
],
"properties": {
"coverageId": {
"type": "integer",
"required": true
},
"timetableId": {
"type": "integer",
"required": true
},
"serviceDayStart": {
"type": "integer",
"required": true
},
"serviceDayEndExclusive": {
"type": "integer",
"required": true
}
}
}
}
},
"timetableMappings": {
"type": "object",
"shape": {
"type": "object"
}
}
}
}
}
}
}示例响应
{
"ok": true,
"data": {
"trainCode": {
"prefix": "G",
"number": 512
},
"items": [
{
"coverageId": 6845,
"timetableId": 5479,
"serviceDayStart": 20575,
"serviceDayEndExclusive": 20680
}
],
"timetableMappings": {
"5479": {
"timetableId": 5479,
"startStation": "汉口",
"endStation": "北京西",
"startOffset": 47340,
"endOffset": 66060,
"stops": [
{
"stationNo": 1,
"stationName": "汉口",
"departOffset": 47340,
"stationTrainCode": {
"prefix": "G",
"number": 512
},
"isStart": true,
"isEnd": false
},
{
"stationNo": 2,
"stationName": "许昌东",
"arriveOffset": 53040,
"departOffset": 53760,
"stationTrainCode": {
"prefix": "G",
"number": 512
},
"isStart": false,
"isEnd": false
},
{
"stationNo": 3,
"stationName": "郑州东",
"arriveOffset": 55140,
"departOffset": 55320,
"stationTrainCode": {
"prefix": "G",
"number": 512
},
"isStart": false,
"isEnd": false
},
{
"stationNo": 4,
"stationName": "高邑西",
"arriveOffset": 60120,
"departOffset": 60240,
"stationTrainCode": {
"prefix": "G",
"number": 512
},
"isStart": false,
"isEnd": false
},
{
"stationNo": 5,
"stationName": "石家庄",
"arriveOffset": 61140,
"departOffset": 61320,
"stationTrainCode": {
"prefix": "G",
"number": 512
},
"isStart": false,
"isEnd": false
},
{
"stationNo": 6,
"stationName": "保定东",
"arriveOffset": 63420,
"departOffset": 63540,
"stationTrainCode": {
"prefix": "G",
"number": 512
},
"isStart": false,
"isEnd": false
},
{
"stationNo": 7,
"stationName": "北京西",
"arriveOffset": 66060,
"stationTrainCode": {
"prefix": "G",
"number": 512
},
"isStart": false,
"isEnd": true
}
]
}
}
},
"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": "额度不足，请稍后再试。"
}
}