QUICKSTART

default

markdown

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

## 🚀 5 分钟快速上手

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

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

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

**天行数据（如可用）**

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

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

---

### 步骤 2：配置 API Key

**方法一：修改配置文件**

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

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

填入你的聚合数据 API Key：

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

**方法二：命令行参数**

不需要修改文件，查询时直接传入：
```bash
python query.py --from 北京 --to 上海 --key abc123def456... --api juhe
```

---

### 步骤 3：测试查询

**查询北京→上海的高铁**：

```bash
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     
...
```

---

## 📖 常用查询示例

### 查询热门线路

```bash
# 北京→西安
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
```

### 查询指定日期

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

### 不使用缓存（强制刷新）

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

---

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

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

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

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

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

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

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

```bash
# 查询西安出发到周边城市
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 数据库：

```bash
# 查询并缓存热门线路
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 未配置"

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

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

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

**可能原因**：
- 网络连接问题
- API 服务暂时不可用

**解决**：
```bash
# 检查网络
ping www.juhe.cn

# 稍后重试
```

### 问题 3：没有查询结果

**可能原因**：
- 车站名称错误
- 日期太远（超过 15 天）
- 该线路没有直达车

**解决**：
```bash
# 检查车站名称（使用标准名称）
python query.py --from 北京西 --to 西安北 --date 2026-03-15 --api juhe --key YOUR_KEY

# 查询临近日期
python query.py --from 北京 --to 西安 --date 2026-03-16 --api juhe --key YOUR_KEY
```

---

## 📊 API 调用统计

查看剩余 API 额度：

```bash
# 访问聚合数据控制台
https://www.juhe.cn/console/usage
```

---

## 🎯 最佳实践

### 1. 建立常用线路缓存

```bash
# 创建一个脚本批量查询并缓存
#!/bin/bash
KEY="YOUR_API_KEY"

# 北京出发
python query.py --from 北京 --to 西安 --key $KEY
python query.py --from 北京 --to 上海 --key $KEY
python query.py --from 北京 --to 广州 --key $KEY
python query.py --from 北京 --to 成都 --key $KEY

# 上海出发
python query.py --from 上海 --to 杭州 --key $KEY
python query.py --from 上海 --to 南京 --key $KEY

# 广州出发
python query.py --from 广州 --to 深圳 --key $KEY
python query.py --from 广州 --to 珠海 --key $KEY
```

### 2. 定期更新缓存

```bash
# 每周更新一次热门线路
0 2 * * 0 /root/.openclaw/workspace/travel/scripts/train_schedule/update_cache.sh
```

### 3. 在旅行规划中使用

规划陕西行程时：
```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
```

将结果写入规划文件，标注"⚠️ 具体车次请以 12306 查询为准"。

---

*最后更新：2026-03-14*
*维护者：Travel Agent*

Uploading file...

Edit message:

Cancel

Editing QUICKSTART