# 麦蕊智数PythonSDK

**Repository Path**: harryxiaocn/mairui-python-sdk

## Basic Information

- **Project Name**: 麦蕊智数PythonSDK
- **Description**: 麦蕊智数的SDK
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-08
- **Last Updated**: 2026-08-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MaiRui API - 麦睿股票API Python客户端

[![PyPI version](https://img.shields.io/pypi/v/mairui-api.svg)](https://pypi.org/project/mairui-api/)
[![Python versions](https://img.shields.io/pypi/pyversions/mairui-api.svg)](https://pypi.org/project/mairui-api/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

麦睿股票API的Python客户端库，提供完整的A股市场数据访问功能。

## 功能特性

- 📊 **股票列表** - 获取沪深股票列表、新股日历、概念指数等
- 💹 **实时行情** - 实时交易数据、五档行情、逐笔成交等
- 📈 **历史数据** - K线数据（分钟/日/周/月）、历史交易记录
- 🏢 **公司信息** - 公司简介、公告、调研报告、股东信息
- 💰 **财务数据** - 资产负债表、利润表、现金流量表、财务指标
- 📉 **技术指标** - MACD、KDJ、BOLL、MA等技术指标
- 🎯 **统计数据** - 涨跌停统计、强势股、趋势股等

## 安装

使用pip安装：

```bash
pip install mairui-api
```

## 快速开始

### 1. 初始化客户端

```python
from mairui import MaiRuiClient

# 使用您的licence初始化客户端
client = MaiRuiClient(licence='YOUR-LICENCE-KEY')
```

### 2. 获取股票列表

```python
# 获取所有股票列表
stock_list = client.stock.get_stock_list()
for stock in stock_list[:5]:
    print(f"{stock['dm']} - {stock['mc']} ({stock['jys']})")

# 输出示例：
# 000001 - 平安银行 (sz)
# 000002 - 万科A (sz)
```

### 3. 获取实时行情

```python
# 获取单只股票实时行情
quote = client.market.get_realtime_quote('000001')
print(f"最新价: {quote['price']}, 涨跌幅: {quote['change_pct']}%")

# 获取实时五档行情
five_levels = client.market.get_realtime_five('000001')
print(f"买一: {five_levels['bid1_price']} ({five_levels['bid1_volume']})")
```

### 4. 获取历史K线数据

```python
# 获取日K线数据（前复权）
kline = client.market.get_history_kline(
    stock_code_market='000001.SZ',
    period='d',           # d=日线, w=周线, m=月线
    adjust_type='qfq',    # qfq=前复权, hfq=后复权, n=不复权
    start_time='20240101',
    end_time='20241231'
)

for day in kline[-5:]:
    print(f"日期: {day['date']}, 收盘: {day['close']}, 成交量: {day['volume']}")
```

### 5. 获取公司信息

```python
# 获取公司简介
profile = client.company.get_company_profile('000001')
print(f"公司名称: {profile['name']}")
print(f"主营业务: {profile['business']}")

# 获取十大股东
shareholders = client.company.get_top_shareholders('000001')
for holder in shareholders[:3]:
    print(f"{holder['name']}: {holder['share_pct']}%")
```

### 6. 获取财务数据

```python
# 获取资产负债表
balance_sheet = client.financial.get_balance_sheet('000001.SZ')
latest = balance_sheet[0]
print(f"总资产: {latest['total_assets']}")
print(f"总负债: {latest['total_liabilities']}")

# 获取利润表
income = client.financial.get_income_statement('000001.SZ')
latest = income[0]
print(f"营业收入: {latest['revenue']}")
print(f"净利润: {latest['net_profit']}")
```

### 7. 获取技术指标

```python
# 获取MACD指标
macd = client.technical.get_macd('000001.SZ', 'd', 'qfq', limit=30)
for item in macd[-5:]:
    print(f"日期: {item['date']}, DIF: {item['dif']}, DEA: {item['dea']}, MACD: {item['macd']}")

# 获取KDJ指标
kdj = client.technical.get_kdj('000001.SZ', 'd', 'qfq', limit=30)
for item in kdj[-5:]:
    print(f"日期: {item['date']}, K: {item['k']}, D: {item['d']}, J: {item['j']}")
```

### 8. 获取涨跌停统计

```python
# 获取涨停股统计
limit_up = client.market.get_limit_up_stats('2024-01-15')
print(f"涨停股票数量: {len(limit_up)}")

# 获取跌停股统计
limit_down = client.market.get_limit_down_stats('2024-01-15')
print(f"跌停股票数量: {len(limit_down)}")
```

## API模块说明

### stock - 股票列表模块
- `get_stock_list()` - 获取股票列表
- `get_new_stock_calendar()` - 获取新股日历
- `get_concept_sectors_list()` - 获取概念指数列表
- `get_primary_sectors_list()` - 获取一级市场板块列表
- `get_sector_detail(sector_name)` - 获取板块明细列表
- `get_trade_calendar(year)` - 获取交易日历

### index - 指数、行业、概念模块
- `get_index_concept_tree()` - 获取指数、行业、概念树
- `get_index_stocks(code)` - 根据指数、行业、概念找相关股票
- `get_stock_concepts(stock_code)` - 根据股票找相关指数、行业、概念

### index_data - 沪深指数数据模块（注意：指数接口不含除权参数）
- `get_index_list()` - 获取沪深主要指数列表
- `get_index_realtime(index_code)` - 获取指数实时交易数据
- `get_index_latest_kline(index_code_market, period)` - 获取指数最新分时
- `get_index_history_kline(index_code_market, period)` - 获取指数历史分时
- `get_index_macd(...)` / `get_index_ma(...)` / `get_index_boll(...)` / `get_index_kdj(...)` - 指数技术指标
- `get_index_pro_latest(...)` / `get_index_pro_history(...)` / `get_index_pro_full_history(...)` - 指数 Pro 专属数据

### pool - 涨跌股池模块
- `get_limit_up_pool(date)` - 获取涨停股池
- `get_limit_down_pool(date)` - 获取跌停股池
- `get_strong_pool(date)` - 获取强势股池
- `get_new_stock_pool(date)` - 获取次新股池
- `get_broken_board_pool(date)` - 获取炸板股池

### market - 市场行情模块
- `get_realtime_data(stock_code)` - 获取实时交易数据（网络源）
- `get_day_ticks(stock_code)` - 获取当天逐笔交易
- `get_realtime_quote(stock_code)` - 获取实时交易数据（券商源）
- `get_realtime_five(stock_code)` - 获取买卖五档盘口
- `get_all_realtime()` - 获取全市场实时行情（包年/钻石/Pro）
- `get_multiple_realtime(codes)` - 获取多股实时行情
- `get_capital_flow(stock_code, ...)` - 获取资金流向数据
- `get_history_ticks(date, code)` - 获取历史逐笔交易
- `get_latest_kline(...)` - 获取最新K线
- `get_history_kline(...)` - 获取历史K线
- `get_limit_price_history(...)` - 获取历史涨跌停价格
- `get_indicators(...)` - 获取行情指标
- `get_vip_history(...)` - 获取企业版历史数据（1m级别）
- `get_instrument(stock_code_market)` - 获取股票基础信息

### company - 公司信息模块
- `get_company_profile(stock_code)` - 获取公司简介
- `get_belonging_indexes(stock_code)` - 获取所属指数
- `get_senior_executives(stock_code)` - 获取历届高管成员
- `get_board_members(stock_code)` - 获取历届董事会成员
- `get_supervisors(stock_code)` - 获取历届监事会成员
- `get_dividend_history(stock_code)` - 获取近年分红
- `get_refinancing_history(stock_code)` - 获取近年增发
- `get_unlock_shares(stock_code)` - 获取解禁限售
- `get_quarterly_profit(stock_code)` - 获取近一年各季度利润
- `get_quarterly_cashflow(stock_code)` - 获取近一年各季度现金流
- `get_performance_forecast(stock_code)` - 获取近年业绩预告
- `get_financial_indicators(stock_code)` - 获取财务指标
- `get_top_shareholders(stock_code)` - 获取十大股东
- `get_circulation_shareholders(stock_code)` - 获取十大流通股东
- `get_shareholder_changes(stock_code)` - 获取股东变化趋势
- `get_fund_holdings(stock_code)` - 获取基金持股

### financial - 财务数据模块
- `get_balance_sheet(...)` - 获取资产负债表
- `get_income_statement(...)` - 获取利润表
- `get_cashflow_statement(...)` - 获取现金流量表
- `get_main_indicators(...)` - 获取财务主要指标
- `get_capital_structure(...)` - 获取公司股本表
- `get_top_holders(...)` - 获取公司十大股东
- `get_circulation_holders(...)` - 获取公司十大流通股东
- `get_shareholder_count(...)` - 获取公司股东数

### technical - 技术指标模块
- `get_macd(...)` - 获取MACD指标
- `get_ma(...)` - 获取MA均线
- `get_boll(...)` - 获取BOLL布林带
- `get_kdj(...)` - 获取KDJ指标

### special - 特色行情模块
- `get_limit_up_performance(stock_code)` - 获取涨跌停表现
- `get_auction_performance(stock_code)` - 获取集合竞价表现
- `get_interactive_qa(stock_code)` - 获取问董秘数据
- `get_exchange_announcement(stock_code)` - 获取交易所公告数据

### pro - Pro专属数据模块（Quant Pro 增强包）
- `get_pro_latest(stock_code_market, dividend='n', limit=5)` - 获取最新分时交易（Pro版）
- `get_pro_history(stock_code_market, dividend='n', ...)` - 获取历史分时交易（Pro版）
- `get_pro_full_history(stock_code, period, dividend, year=None)` - 获取完整历史分时交易（Pro版）

## 异常处理

```python
from mairui import MaiRuiClient
from mairui.exceptions import (
    MaiRuiAPIError,
    MaiRuiAuthError,
    MaiRuiRateLimitError,
    MaiRuiNetworkError
)

client = MaiRuiClient(licence='YOUR-LICENCE-KEY')

try:
    stock_list = client.stock.get_stock_list()
except MaiRuiAuthError:
    print("认证失败，请检查您的licence是否有效")
except MaiRuiRateLimitError:
    print("超过请求频率限制，请稍后再试")
except MaiRuiNetworkError as e:
    print(f"网络请求失败: {e}")
except MaiRuiAPIError as e:
    print(f"API错误: {e}")
```

## 参数说明

### 股票代码格式
- 不带市场后缀：`000001`
- 带市场后缀：`000001.SZ` (深圳) 或 `600000.SH` (上海)

### K线周期类型
- `1` - 1分钟（企业版/Pro专属）
- `5` - 5分钟
- `15` - 15分钟
- `30` - 30分钟
- `60` - 60分钟
- `d` - 日线
- `w` - 周线
- `m` - 月线
- `y` - 年线

### 复权方式
- `n` - 不复权
- `qfq` - 前复权
- `hfq` - 后复权

## 请求频率限制

根据您的licence类型，API有不同的请求频率限制：
- 普通版：1分钟300次
- 包年版：1分钟3000次
- 钻石版：1分钟6000次

建议在代码中添加适当的延迟，避免触发频率限制。

## 完整示例

查看 `examples/` 目录获取更多完整示例代码：

- `examples/basic_usage.py` - 基础功能示例
- `examples/advanced_usage.py` - 高级功能示例
- `examples/new_endpoints.py` - 依据最新文档新增/更新的接口示例

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

## 相关链接

- [麦睿API官网](https://www.mairuiapi.com/)
- [API文档](https://www.mairuiapi.com/doc.html)
- [获取licence](https://www.mairuiapi.com/)

## 贡献

欢迎提交Issue和Pull Request！

## 免责声明

本库仅供学习和研究使用，使用者需遵守麦睿API的使用条款。股市有风险，投资需谨慎。