SOLUTION

default

markdown

# 全国高铁列车时刻表数据获取方案

## 📋 任务概述

**用户需求**：获取最新的全国高铁列车时刻表，用于后续旅行规划

**挑战**：
1. 12306 官方数据反爬严格（验证码、IP 限制、加密）
2. 数据量巨大（5000+ 线路，10000+ 车次）
3. 数据动态更新（季度调图、临时加开）

---

## ✅ 解决方案

### 推荐方案：第三方 API + 本地缓存

**核心思路**：
1. 使用第三方 API 服务（天行数据/聚合数据）实时查询
2. 查询结果缓存到本地 SQLite 数据库
3. 优先查缓存，缓存没有再调用 API
4. 定期（每周）更新热门线路

**优势**：
- ✅ 合法合规（购买商业 API 服务）
- ✅ 数据稳定可靠
- ✅ 无需维护复杂爬虫
- ✅ 有免费额度（100 次/天）
- ✅ 成本可控（¥0.01-0.02/次）

---

## 📁 已创建文件

```
/root/.openclaw/workspace/travel/scripts/train_schedule/
├── README.md           # 完整方案说明文档
├── QUICKSTART.md       # 5 分钟快速上手指南
├── query.py            # Python 查询脚本
├── update_cache.sh     # 批量更新缓存脚本
└── train_schedule.db   # SQLite 数据库（首次查询后创建）
```

---

## 🚀 快速开始

### 步骤 1：申请 API Key（5 分钟）

**推荐：天行数据**（完全免费，100 次/天）

1. 访问：https://www.tianapi.com
2. 注册账号
3. 开通"火车票务查询"接口
4. 复制 API Key

### 步骤 2：测试查询

```bash
cd /root/.openclaw/workspace/travel/scripts/train_schedule

# 查询北京→上海
python query.py --from 北京 --to 上海 --api tianapi --key YOUR_API_KEY
```

### 步骤 3：批量缓存热门线路

```bash
# 批量查询并缓存 35 条热门线路
./update_cache.sh YOUR_API_KEY
```

---

## 💡 在旅行规划中的使用

### 场景 1：规划时查询车次

```bash
# 规划陕西行程时，查询北京→西安
python query.py --from 北京 --to 西安 --api tianapi --key YOUR_KEY

# 输出示例：
# G655  北京西→西安北  07:38-12:38  5h  ¥515
```

写入行程规划：
```markdown
**交通**：
- 北京西→西安北：高铁 G655（07:38-12:38，¥515）
> ⚠️ 具体车次请以 12306 查询为准
```

### 场景 2：查询多个城市

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

### 场景 3：建立本地数据库

```bash
# 第一次查询后自动缓存
python query.py --from 北京 --to 西安 --api tianapi --key YOUR_KEY

# 24 小时内再次查询会使用缓存（不消耗 API 额度）
python query.py --from 北京 --to 西安 --api tianapi --key YOUR_KEY
# 输出：✓ 从缓存获取到 45 条车次信息
```

---

## 📊 API 服务商对比

| 服务商 | 免费额度 | 价格 | 推荐度 | 文档 |
|--------|---------|------|--------|------|
| **天行数据** | 100 次/天 | 免费 | ⭐⭐⭐⭐⭐ | https://www.tianapi.com |
| **聚合数据** | 100 次/天 | 免费 | ⭐⭐⭐⭐ | https://www.juhe.cn |
| **阿里云市场** | 100 次/月 | ¥0.02/次 | ⭐⭐⭐ | https://market.aliyun.com |
| **万维易源** | 50 次/天 | ¥0.015/次 | ⭐⭐⭐ | https://www.showapi.com |

**推荐**：天行数据（完全免费，额度充足）

---

## 💰 成本估算

### 免费方案
- **天行数据**：100 次/天免费
- **用途**：日常旅行规划完全够用

### 付费方案（如需更多查询）
- **单价**：¥0.01-0.02/次
- **月度预算**：
  - 1000 次/月：¥10-20
  - 10000 次/月：¥100-200

### 优化策略
1. **缓存优先**：24 小时内相同查询不消耗额度
2. **批量查询**：一次性缓存热门线路
3. **多 Key 轮换**：申请多个账号

---

## 🔧 技术实现

### 查询脚本（query.py）

**功能**：
- 支持天行数据、聚合数据
- SQLite 本地缓存（24 小时有效期）
- 命令行参数查询
- 自动创建数据库和表

**使用方法**：
```bash
python query.py --from 出发站 --to 到达站 --date 日期 --api 数据源 --key API_KEY
```

### 批量更新脚本（update_cache.sh）

**功能**：
- 批量查询 35 条热门线路
- 自动缓存到数据库
- 显示统计信息

**使用方法**：
```bash
./update_cache.sh YOUR_API_KEY
```

### 数据库结构

```sql
-- 车次表
CREATE TABLE trains (
    id INTEGER PRIMARY KEY,
    train_no TEXT,              -- 车次号（如 G655）
    from_station TEXT,          -- 出发站
    to_station TEXT,            -- 到达站
    departure_time TEXT,        -- 出发时间
    arrival_time TEXT,          -- 到达时间
    duration TEXT,              -- 历时
    query_date TEXT,            -- 查询日期
    created_at TIMESTAMP        -- 创建时间
);

-- 站点表
CREATE TABLE stations (
    id INTEGER PRIMARY KEY,
    station_name TEXT,          -- 站点名称
    station_code TEXT,          -- 站点代码
    city_name TEXT,             -- 城市名
    province TEXT               -- 省份
);
```

---

## ⚠️ 注意事项

### 1. API 使用限制
- 天行数据：100 次/天，次日 0 点重置
- 不要频繁调用（建议间隔 1-2 秒）
- 优先使用缓存

### 2. 车站名称
使用标准名称：
- ✅ 北京、北京西、北京南
- ❌ 北京市、北京站（除非确实叫这个名）

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

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

---

## 📈 后续优化

### 短期（1-2 周）
- [ ] 申请天行数据 API Key
- [ ] 测试查询功能
- [ ] 缓存热门线路（北京、上海、西安等）
- [ ] 集成到旅行规划流程

### 中期（1-2 月）
- [ ] 建立定时任务（每周更新缓存）
- [ ] 添加更多数据源（作为备选）
- [ ] 优化查询性能
- [ ] 添加 Web 界面（可选）

### 长期（3-6 月）
- [ ] 积累完整时刻表数据库
- [ ] 实现智能推荐（最佳车次、换乘方案）
- [ ] 票价监控（低价提醒）
- [ ] 余票监控（自动抢票）

---

## 📚 参考资源

### API 服务商
- 天行数据：https://www.tianapi.com
- 聚合数据：https://www.juhe.cn
- 阿里云市场：https://market.aliyun.com

### 官方数据源
- 12306 官网：https://www.12306.cn
- 铁路客服：12306

### 技术文档
- `README.md` - 完整方案说明
- `QUICKSTART.md` - 5 分钟快速上手
- `query.py` - 查询脚本源码

---

## 🎯 下一步行动

### 立即可做
1. **申请 API Key**（5 分钟）
   - 访问 https://www.tianapi.com
   - 注册并开通"火车票务查询"
   - 复制 API Key

2. **测试查询**（2 分钟）
   ```bash
   cd /root/.openclaw/workspace/travel/scripts/train_schedule
   python query.py --from 北京 --to 上海 --api tianapi --key YOUR_KEY
   ```

3. **批量缓存**（10 分钟）
   ```bash
   ./update_cache.sh YOUR_KEY
   ```

### 旅行规划时
1. 查询目标线路车次
2. 选择合适车次写入规划
3. 标注"⚠️ 具体车次请以 12306 查询为准"
4. 建议用户提前 7-15 天购票

---

*创建日期：2026-03-14*  
*维护者：Travel Agent*  
*版本：v1.0*

Uploading file...

Edit message:

Cancel

Editing SOLUTION