首页 新闻动态 知识

火车票API怎么接入站站查询车次查询与余票查询如何分流

发布时间：2026-08-11 10:17 点击：5699次

接入火车票 API 前先判断用户是在找两站之间的车次、查看某一车次的经停路线，还是查询指定日期余票。三种问题分别对应站站查询、车次查询和余票查询，参数与结果不能混用。

三个接口分别解决什么问题

极速数据的火车查询 API 文档提供三个查询入口：

用户问题 接口 必要输入 主要结果
从出发站到到达站有哪些车次 /train/station2s start、end 车次、车型、出到站、时间、历时、距离和票价字段
某个车次经过哪些站 /train/line trainno 经停车站、站序、到发时间、停留时间和里程
某天两站之间还有哪些席别余票 /train/ticket start、end、date 车次、席别余票数量、票价和车站代码等

站站查询回答“有哪些选择”，车次查询回答“这趟车怎么走”，余票查询回答“指定日期当前还能看到什么席别信息”。产品界面可以连续使用三个接口，但后端应保留独立请求和缓存键，不能把某个接口缺失的字段从另一个时间点的结果中直接拼接。

站站查询怎么接

站站查询地址是 https://api.jisuapi.com/train/station2s，支持 GET、POST。start 和 end 必填，ishigh 与 date 可选。ishigh 用于是否筛选高铁，date 用于指定时间。

GET https://api.jisuapi.com/train/station2s?appkey=YOUR_APPKEY&start=URL_ENCODED_START&end=URL_ENCODED_END&ishigh=0

出发站和到达站来自用户输入时，应先去除首尾空格、做 UTF-8 编码，并阻止两者都为空或完全相同的无效请求。页面若允许“只看高铁”，应把界面状态明确映射到 ishigh，而不是根据车次首字母在前端二次猜测。

返回字段包括 trainno、type、station、endstation、departuretime、arrivaltime、costtime、distance、isend 以及不同席别的票价字段。适合把它们整理成“车次基本信息 + 本段行程 + 席别价格”三层；字段为空时表示当前响应未提供，不要默认写成免费或无票。

车次查询什么时候调用

用户已经选定车次并要查看完整经停路线时，再调用 https://api.jisuapi.com/train/line。该接口当前使用 GET，trainno 必填，date 可选。

GET https://api.jisuapi.com/train/line?appkey=YOUR_APPKEY&trainno=URL_ENCODED_TRAIN_NO

返回的每个站点包含 sequenceno、station、day、arrivaltime、departuretime、stoptime、distance 和 isend 等字段。排序时优先使用站序 sequenceno，不要只按到达时间排序，因为跨日车次会出现日期变化；day 和文档中的 date 需要一起用于解释跨日行程。

车次查询还返回出发站、终点站、车型名称和多种席别票价字段。它适合制作经停站详情，但不等于指定日期余票。用户点击“还有没有票”时必须转到余票查询，不能把路线接口中的票价字段误写成可售库存。

余票查询如何建模

余票接口为 https://api.jisuapi.com/train/ticket，支持 GET、POST。start、end、date 三项均为必填参数。

GET https://api.jisuapi.com/train/ticket?appkey=YOUR_APPKEY&start=URL_ENCODED_START&end=URL_ENCODED_END&date=YYYY-MM-DD

响应包含车次、车型、始发站、终点站、本段出到站、到发时间、用时、距离，以及多组席别数量和票价。例如 numsw、numyd、numed、numrw、numyw、numwz 分别对应文档所列的商务座、一等座、二等座、软卧、硬卧和无座数量；相应价格使用 pricesw、priceyd、priceed 等字段。

不要把这些平铺字段直接扩散到订单表。可以先转成统一的席别数组：

{
  "seat_type": "second_class",
  "availability_raw": "接口原始值",
  "price_raw": "接口原始值",
  "source_time": "本次查询时间"
}

seat_type 是业务系统自建枚举，示例不代表极速数据原始字段。保留 availability_raw 很重要，因为余票字段可能不仅出现普通数字，还可能存在空值或其他状态表达；只有在完成实际响应样本核验后，才能为每种值建立可售、无票、未知等内部状态。

余票具有明显时效性。页面应显示查询日期和本次刷新时间，缓存键至少包含出发站、到达站和日期。用户改变任意一项时都应重新查询，不能复用另一天或反向路线的数据。

请求和返回要怎样分层判断

三个接口都使用 APPKEY。后端建议采用相同的处理骨架：

校验业务输入
  -> 设置 HTTPS 超时并发送请求
  -> 判断 HTTP 状态
  -> 解析 JSON
  -> 判断业务状态
  -> 校验 result 的结构
  -> 转换为站站、线路或余票内部模型

火车文档列出的业务错误码中，201 表示车次为空，202 表示始发站或到达站为空，203 表示没有信息；系统错误码 101 至 104 分别对应 APPKEY 不存在、已过期、无权限和超过次数限制。

参数错误不应自动重试，应回到输入或程序校验；203 要向用户显示“当前条件没有信息”，并保留修改车站或日期的入口；网络超时和 5xx 可以有限重试，但应设置退避与总时长上限；鉴权和次数限制属于服务端配置问题，只向管理员告警，不把 APPKEY 或账户状态暴露给终端用户。

APPKEY 与日志怎么保护

请求必须由后端服务发出。网页、小程序和 APP 只把经过校验的出发站、到达站、车次或日期提交给自有后端；后端从环境变量或密钥管理服务取得 APPKEY，再调用极速数据接口。

日志可以记录端点名称、脱敏后的查询条件、耗时、HTTP 状态、业务状态和追踪号。完整 APPKEY 不得写入日志。用户行程搜索也可能形成行为画像，应按业务所需控制留存周期和访问权限，而不是长期保留每次搜索明细。

火车查询结果有哪些边界

接口适合做行程搜索、车次路线、到发时间、席别信息和票价展示，但查询结果不代表已经锁票、占座或购票成功。余票和价格会随时间变化，最终交易应以实际购票渠道的确认结果为准。涉及自动下单、退改签、乘车人信息或支付时，需要另行对接有相应能力与授权的业务系统，不能由查询接口推断完成。

截至 2026 年 8 月 11 日，站站、车次和余票三个入口及上述字段来自极速数据当前火车查询 API 文档。上线前应再次核对接口权限、参数、配额和数据时效要求。

总结

火车票 API 的接入顺序应跟着用户问题走：先用站站查询列出候选，用车次查询解释经停路线，需要指定日期库存时再调用余票查询。把三个结果模型分开，并对日期、业务错误和数据时效单独处理，才能避免把路线、票价和余票混成错误结论。