# 麦蕊智数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-01-08

## 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_sectors_list()` - 获取概念指数列表
- `get_primary_list()` - 获取主题指数列表
- `get_sectors(sector_name)` - 获取板块成分股

### market - 市场行情模块
- `get_realtime_data(stock_code)` - 获取实时交易数据
- `get_realtime_quote(stock_code)` - 获取实时行情
- `get_realtime_five(stock_code)` - 获取实时五档
- `get_history_kline(...)` - 获取历史K线
- `get_latest_kline(...)` - 获取最新K线
- `get_limit_up_stats(date)` - 获取涨停股统计
- `get_limit_down_stats(date)` - 获取跌停股统计
- `get_all_realtime()` - 获取全市场实时行情

### company - 公司信息模块
- `get_company_profile(stock_code)` - 获取公司简介
- `get_announcements(stock_code)` - 获取历年公告
- `get_top_shareholders(stock_code)` - 获取十大股东
- `get_dividend_history(stock_code)` - 获取历年分红
- `get_performance_forecast(stock_code)` - 获取业绩预告

### financial - 财务数据模块
- `get_balance_sheet(...)` - 获取资产负债表
- `get_income_statement(...)` - 获取利润表
- `get_cashflow_statement(...)` - 获取现金流量表
- `get_financial_indicators(stock_code)` - 获取财务指标
- `get_per_share_index(...)` - 获取每股指标

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

## 异常处理

```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分钟
- `5` - 5分钟
- `15` - 15分钟
- `30` - 30分钟
- `60` - 60分钟
- `d` - 日线
- `w` - 周线
- `m` - 月线

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

## 请求频率限制

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

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

## 完整示例

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

## 许可证

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

## 相关链接

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

## 贡献

欢迎提交Issue和Pull Request！

## 免责声明

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