# 数据获取模块 (data-fetch)

使用 mairui API 获取指数K线数据（支持时间范围参数）

## 文件说明

- `mairui_fetcher.py` - 核心数据获取模块
- `fetch_cyb50.py` - 快速获取创业板50数据脚本
- `data/` - 数据保存目录（自动创建）

## 使用方法

### 1. 快速获取创业板50数据

```bash
cd ~/.openclaw/workspace/cyb50-quant/cat-fly/data-fetch
python fetch_cyb50.py
```

### 2. 命令行参数获取

```bash
# 获取创业板50，2023年至今，30分钟K线
python mairui_fetcher.py --start 2023-01-01

# 获取2024年全年日线数据
python mairui_fetcher.py --code 399673.SZ --tf d --start 2024-01-01 --end 2024-12-31

# 获取上证指数60分钟数据
python mairui_fetcher.py --code 000001.SH --tf 60 --start 2024-01-01

# 只获取不保存
python mairui_fetcher.py --start 2023-01-01 --no-save
```

### 3. 在代码中使用

```python
from mairui_fetcher import fetch_cyb50_30min, MairuiDataFetcher

# 快速获取创业板50的30分钟数据
df = fetch_cyb50_30min(start_date="2023-01-01", end_date="2025-03-25")

# 自定义获取
fetcher = MairuiDataFetcher(data_dir="./my_data")

# 获取日线数据
df = fetcher.fetch_data(
    index_code="399673.SZ",
    timeframe="d",  # d=日线, 30=30分钟, 60=60分钟
    start_date="2023-01-01",
    end_date="2025-03-25"
)

# 获取30分钟数据
df = fetcher.fetch_30min_data(
    index_code="399673.SZ",
    start_date="2023-01-01",
    end_date="2025-03-25"
)

# 保存数据
fetcher.save_to_csv(df, "my_data.csv")

# 加载数据
df = fetcher.load_from_csv("my_data.csv")
```

## API 接口说明

### 历史数据接口

```
https://api.mairuiapi.com/hsindex/history/{指数代码}/{分时级别}/{token}?st={开始时间}&et={结束时间}
```

**参数说明：**

| 参数 | 说明 | 示例 |
|------|------|------|
| 指数代码 | 指数代码.市场 | `399673.SZ`, `000001.SH` |
| 分时级别 | K线周期 | `d`=日线, `30`=30分钟, `60`=60分钟 |
| token | API密钥 | `AE17EE23-AAE4-492F-A959-EC883DFA5A76` |
| st | 开始时间 | `20230101` (YYYYMMDD格式) |
| et | 结束时间 | `20250325` (YYYYMMDD格式) |

**完整示例：**
```
https://api.mairuiapi.com/hsindex/history/399673.SZ/30/AE17EE23-AAE4-492F-A959-EC883DFA5A76?st=20230101&et=20250325
```

### 支持的指数代码

| 名称 | 代码 | 别名 |
|------|------|------|
| 创业板50 | 399673.SZ | cyb50 |
| 创业板指 | 399006.SZ | cy |
| 上证指数 | 000001.SH | sh |
| 沪深300 | 000300.SH | hs300 |
| 深证成指 | 399001.SZ | sz |

### 支持的K线周期

| 代码 | 说明 |
|------|------|
| `d` | 日线 |
| `30` | 30分钟线 |
| `60` | 60分钟线 |

## 返回数据格式

| 列名 | 说明 |
|------|------|
| datetime | 日期时间 |
| open | 开盘价 |
| high | 最高价 |
| low | 最低价 |
| close | 收盘价 |
| volume | 成交量 |
| amount | 成交额 |

## 数据量估算

创业板50指数 30分钟K线数据量：
- 每天交易4小时 = 8条30分钟K线
- 每年约250个交易日 = 2000条/年
- 2023年至今（约2.2年）≈ 4400条数据

## 依赖安装

```bash
pip install requests pandas
```

## 注意事项

1. **API限制**: 注意mairui API的调用频率限制
2. **数据延迟**: 免费数据可能有15分钟延迟
3. **日期格式**: 代码中传入 `YYYY-MM-DD` 格式，API会自动转换为 `YYYYMMDD`
4. **时间范围**: 可获取2005年至今的数据
5. **空数据处理**: 如果API返回空数据，会返回空的DataFrame

## 更新日志

### v2.0 (2025-03-25)
- ✨ 支持时间范围参数 (`st`, `et`)
- ✨ 支持多种K线周期 (日线/30分钟/60分钟)
- ✨ 代码更简洁，无需分页
- ✨ 添加命令行参数支持

### v1.1 (2025-03-25)
- 支持历史数据接口自动分页获取

### v1.0 (2025-03-25)
- 初始版本