高铁时刻表查询 - 快速开始指南

🚀 5 分钟快速上手

步骤 1：申请 API Key（推荐聚合数据）⭐

聚合数据（免费 100 次/天） ⭐⭐⭐⭐⭐ 强烈推荐

访问：https://www.juhe.cn
点击右上角"注册"，用手机号或邮箱注册
登录后进入控制台：https://www.juhe.cn/console
在左侧菜单或 API 市场搜索"火车"或"票务"
找到"火车票务查询"或"12306 车次查询"
点击"立即申请"（免费，立即生效）
在"我的 API"或"数据中心"中找到刚开通的接口
复制 API Key（一串字母数字）

天行数据（如可用）

⚠️ 注意：天行数据的火车 API 可能已下架，如找不到请使用聚合数据

访问：https://www.tianapi.com
注册并登录
在 API 市场搜索"火车"
如找到"火车票务查询"，申请开通
获取 API Key

步骤 2：配置 API Key

方法一：修改配置文件

编辑 query.py，在文件顶部找到：

CONFIG = {
    "tianapi_key": "",  # 天行数据 API Key（可能已下架）
    "juhe_key": "",     # 聚合数据 API Key ⭐ 推荐
    ...
}

填入你的聚合数据 API Key：

CONFIG = {
    "tianapi_key": "",
    "juhe_key": "abc123def456...",  # 你的聚合数据 API Key
    ...
}

方法二：命令行参数

不需要修改文件，查询时直接传入：

python query.py --from 北京 --to 上海 --key abc123def456... --api juhe

步骤 3：测试查询

查询北京→上海的高铁：

cd /root/.openclaw/workspace/travel/scripts/train_schedule
python query.py --from 北京 --to 上海 --api juhe --key YOUR_JUHE_KEY

输出示例：

→ 正在查询 北京 → 上海 的车次...
✓ 查询成功，获取到 45 条车次信息

车次         出发站        到达站        出发时间      到达时间      历时       
----------------------------------------------------------------------
G1         北京南        上海虹桥      09:00       13:28       4h28m     
G3         北京南        上海虹桥      10:00       14:28       4h28m     
G5         北京南        上海虹桥      11:00       15:28       4h28m     
...

📖 常用查询示例

查询热门线路

# 北京→西安
python query.py --from 北京 --to 西安 --api juhe --key YOUR_KEY

# 北京→上海
python query.py --from 北京 --to 上海 --api juhe --key YOUR_KEY

# 上海→杭州
python query.py --from 上海 --to 杭州 --api juhe --key YOUR_KEY

# 广州→深圳
python query.py --from 广州 --to 深圳 --api juhe --key YOUR_KEY

查询指定日期

# 查询 2026-03-15 的车次
python query.py --from 北京 --to 西安 --date 2026-03-15 --api juhe --key YOUR_KEY

不使用缓存（强制刷新）

python query.py --from 北京 --to 上海 --no-cache --api juhe --key YOUR_KEY

💡 在旅行规划中的使用方法

场景 1：规划时查询大致车次

在制定旅行规划时，先查询目标线路的车次：

# 查询北京→西安的所有车次
python query.py --from 北京 --to 西安 --api juhe --key YOUR_KEY

选择一个合适的车次（如 G655 07:38-12:38），写入行程规划：

**交通**：
- 北京西→西安北：高铁 G655（07:38-12:38，¥515）

场景 2：批量查询多个城市

# 查询西安出发到周边城市
python query.py --from 西安 --to 宝鸡 --api juhe --key YOUR_KEY
python query.py --from 西安 --to 咸阳 --api juhe --key YOUR_KEY
python query.py --from 西安 --to 汉中 --api juhe --key YOUR_KEY

场景 3：建立本地数据库

第一次查询后，数据会自动缓存到 SQLite 数据库：

# 查询并缓存热门线路
python query.py --from 北京 --to 西安 --api juhe --key YOUR_KEY
python query.py --from 北京 --to 上海 --api juhe --key YOUR_KEY
python query.py --from 北京 --to 广州 --api juhe --key YOUR_KEY

后续查询会优先使用缓存（24 小时内有效），节省 API 调用次数。

⚠️ 注意事项

1. API 额度限制

聚合数据：100 次/天，次日 0 点重置 ⭐ 推荐
天行数据：可能已下架

建议：

优先使用缓存（--no-cache 只在需要时使用）
热门线路只查询一次，后续使用缓存
多个 API Key 轮换使用

2. 车站名称

使用标准车站名称：

✅ 正确：北京、北京西、北京南
❌ 错误：北京市、北京站（除非确实叫这个名）

不确定时：

在 12306 App 查询车站标准名称
或使用简称（如"北京"会自动匹配北京/北京西/北京南）

3. 查询日期

12306 通常提前 15 天放票
查询未来太远的日期可能没有结果
建议查询 7-15 天内的车次

4. 数据准确性

API 数据来自 12306，但可能有延迟
重要：最终购票前请在 12306 官方渠道核实
在行程规划中标注"⚠️ 具体车次请以 12306 查询为准"

🔧 故障排查

问题 1：提示"API Key 未配置"

解决：

# 方法 1：在命令行传入（推荐）
python query.py --from 北京 --to 西安 --key YOUR_JUHE_KEY --api juhe

# 方法 2：修改配置文件
vim query.py  # 编辑 CONFIG 中的 juhe_key

问题 2：查询失败，返回"网络错误"

可能原因：

网络连接问题
API 服务暂时不可用

解决：

# 检查网络
ping www.juhe.cn

# 稍后重试

问题 3：没有查询结果