cyb50-quant/cat-fly/data-fetch/README.md

数据获取模块 (data-fetch)

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

文件说明

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

使用方法

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

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

2. 命令行参数获取

# 获取创业板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. 在代码中使用

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条数据

依赖安装

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)

• 初始版本