火车票余票信息查询免费API接口教程

接口介绍

接口盒子(http://www.apihz.cn)提供的火车票余票信息查询API接口，可以查询指定日期、出发地到目的地的火车票余票信息。该接口支持GET和POST请求方式，普通用户可使用免费版本，彩钻和炫钻用户可获得更高成功率。

核心功能

• 查询指定日期、出发地到目的地的火车票余票信息
• 返回车次信息、余票情况、行程时间等详细数据
• 支持后续调用票价查询和车次全程站点查询接口

请求参数

返回参数说明

调用示例(Python)

python

运行

复制

import requests

def query_train_tickets(add, end, date):
    # 替换为你的实际ID和KEY
    params = {
        'id': 'YOUR_USER_ID',
        'key': 'YOUR_API_KEY',
        'add': add,
        'end': end,
        'y': date[:4],  # 年
        'm': date[5:7], # 月
        'd': date[8:10] # 日
    }
    
    url = 'https://cn.apihz.cn/api/12306/api.php'
    response = requests.get(url, params=params)
    
    if response.status_code == 200:
        data = response.json()
        if isinstance(data, list):
            return data  # 成功返回车次列表
        else:
            print(f"查询失败: {data.get('msg', '未知错误')}")
            return []
    else:
        print(f"请求失败，状态码: {response.status_code}")
        return []

# 使用示例
tickets = query_train_tickets('绵阳', '上海', '2025-06-30')

# 打印查询结果
if tickets:
    print(f"查询到{len(tickets)}个车次信息:")
    for train in tickets:
        print(f"\n车次: {train['train_number']}")
        print(f"出发: {train['depart_name']}({train['depart_time']}) → 到达: {train['arrive_name']}({train['arrive_time']})")
        print(f"历时: {train['duration']}")
        print("余票情况:")
        for seat in train['seats']:
            stock = "有票" if seat['stock'] == -1 else f"余票{seat['stock']}张" if seat['stock'] > 0 else "无票"
            print(f"  {seat['type']}: {stock}")
else:
    print("未查询到车次信息")

使用注意事项

1. ​用户权限​：

   • 普通用户：本地线路调用，成功率无保障
   • 彩钻/炫钻用户：本地+代理双模式调用，成功率超高

2. ​调用限制​：

   • 免费用户每分钟有调用频次限制
   • 请使用自己的ID与KEY，避免使用公共示例账号
   • 每日调用无上限

3. ​缓存机制​：

   • 查询成功后的信息有60秒缓存期

4. ​Cookie使用​：

   • 平台提供默认cookie
   • 如多次查询失败，可提供自己的cookie(JSESSIONID值)

常见问题处理

1. ​授权失败​：

   • 确认ID和KEY是否正确
   • 检查是否有特殊字符需要编码

2. ​无返回数据​：

   • 检查出发地和目的地名称是否正确
   • 确认查询日期是否正确（至少提前1天查询）

3. ​查询频繁​：

   • 降低调用频率
   • 考虑升级为彩钻/炫钻用户

参考资料

接口详细文档和版权信息：https://www.apihz.cn/api/12306api.html

通过该API，开发者可以轻松实现火车票余票查询功能，为出行规划提供数据支持。请合理使用API资源，遵守相关使用条款。