Metadata-Version: 2.4
Name: alphakit-sdk
Version: 0.2.8
Summary: AlphaKit — Python A股行情、估值与行业数据客户端，返回 pandas DataFrame
Author: AlphaKit Team
License: MIT
Project-URL: Homepage, https://alphakit.cn/
Project-URL: Documentation, https://alphakit.cn/help/sdk/quick-start.html
Keywords: finance,a-share,market-data,pandas,api,quant
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: pandas>=1.3.0

# AlphaKit SDK：Python A 股行情、估值与行业数据

AlphaKit SDK（包名 `alphakit-sdk`，导入名 `alphakit`）是 [AlphaKit](https://alphakit.cn/) 数据服务的 Python 客户端。查询结果返回 `pandas.DataFrame`，便于接入数据清洗、绘图和自己的研究流程。

客户端提供股票日线、每日估值、指数、ETF、申万行业、同花顺板块及部分市场行为数据的查询方法。具体接口、字段、历史范围和配额以服务端及账户权限为准。仅供个人学习与研究使用。

## 安装与申请访问

```bash
pip install alphakit-sdk
```

需要 Python 3.8 或以上。安装客户端后，还需要有效的 Token 和数据服务地址。

通过微信 **dfzzq719** 联系 AlphaKit，说明想使用 SDK 还是网页工具，以及需要的数据类别。管理方会说明可开通范围、配额及使用条件，并提供访问凭证和数据服务地址。网页登录需要用户名和 Token；SDK 查询使用 Token。

[访问申请说明](https://alphakit.cn/help/sdk/access.html) · [SDK 入门指南](https://alphakit.cn/help/sdk/quick-start.html)

## 第一次查询：指定历史日线范围

在自己的运行环境中设置 `ALPHAKIT_TOKEN` 和 `ALPHAKIT_BASE_URL`，值分别使用管理方提供的 Token 和 HTTPS 数据服务地址。不要将真实 Token 写入公开代码、截图或仓库。

```python
import os
import alphakit as ak
from alphakit.exceptions import AlphaKitError

api = ak.AlphaKit(
    token=os.environ["ALPHAKIT_TOKEN"],
    base_url=os.environ["ALPHAKIT_BASE_URL"],
)

try:
    df = api.daily(
        ts_code="000001.SZ",
        start_date="20260101",
        end_date="20260630",
    )
    if df.empty:
        print("本次查询没有返回数据，请核对代码、日期与账户可用范围。")
    else:
        df = df.sort_values("trade_date").reset_index(drop=True)
        print(df[["ts_code", "trade_date", "close", "vol"]].tail())
except AlphaKitError as exc:
    print(f"查询失败，错误码：{exc.code}")
```

日期格式为 `YYYYMMDD`，股票代码包含交易所后缀，如 `000001.SZ`、`600519.SH`。仅向 `daily()` 传入 `ts_code`、不带任何日期参数时，客户端会补入最近 365 天的起止日期。研究和复现案例时，建议显式指定日期范围。

## 已有查询方法

以下是客户端已有方法，不代表每个账户都已开通全部数据。

| 数据类别 | 方法示例 | 可以做什么 |
|---|---|---|
| 股票信息与日线 | `stock_basic()`、`daily()` | 查询证券基础信息与历史日线 |
| 每日估值 | `daily_basic()` | 查询 PE、PB、市值等每日指标 |
| 复权与技术因子 | `adj_factor()`、`stk_factor()` | 获取复权因子及服务端已有技术因子 |
| 指数 | `index_daily()`、`index_dailybasic()` | 查询指数行情与可用每日指标 |
| 申万行业 | `sw_l1()`、`sw_l2()`、`sw_l3()`、`sw_daily()`、`sw_stock_industry()` | 查询行业分类、行业日线与股票行业映射 |
| 同花顺板块 | `ths_index()`、`ths_daily()`、`ths_member()` | 查询板块清单、日线与成分 |
| ETF | `etf_basic()`、`etf_daily()`、`etf_nav()`、`etf_share()`、`etf_theme_map()` | 查询 ETF 基础信息、行情、净值、份额与主题映射 |
| 市场行为 | `moneyflow()`、`moneyflow_dc()`、`margin()`、`margin_detail()`、`limit_list_d()`、`top_list()`、`hm_detail()`、`kpl_list()`、`suspend_d()` | 查询资金流向、两融、涨跌停、龙虎榜及停复牌信息 |
| 期权 | `opt_basic()`、`opt_daily()` | 查询期权基础信息与日线 |
| 通用查询 | `query(api_name, **params)` | 查询服务端支持且账户有权访问的其他接口 |

例如，查询同一只股票的估值与行业映射：

```python
valuation = api.daily_basic(
    ts_code="000001.SZ", start_date="20260101", end_date="20260630"
)
industry = api.sw_stock_industry(ts_code="000001.SZ")
```

`weekly`、`monthly`、`fina_indicator` 没有对应的专用客户端方法。若服务端支持且账户已获授权，可通过 `api.query("接口名", **参数)` 调用；通用方法不会自动增加数据权限。

## 从代码查询到网页研究

[AlphaKit 网站](https://alphakit.cn/)提供与 SDK 配套的网页研究工具，可以查看图表、比较行业和核对历史研究结果。

| 网页工具 | 研究用途 |
|---|---|
| AlphaView | 结合行情、指标和历史分位查看市场、行业或个股 |
| 行业轮动 | 观察行业相对强弱与动量的变化 |
| 八维因子评分 | 查看评分日、各维度构成及同一口径下的比较 |
| 策略历史回测 | 核对历史样本中的收益、回撤、基准、模拟调仓记录与费用假设 |

部分网页功能处于 Beta 阶段。网页工具与数据接口均按账户权限开放，具体范围以账户配置为准。历史分位和历史回测描述所选样本中的表现。

## 教程与公开指南

- [SDK 入门：安装、凭证与第一次查询](https://alphakit.cn/help/sdk/quick-start.html)
- [下载 Python 示例包](https://alphakit.cn/help/sdk/examples/alphakit-sdk-examples.zip)（解压后保留源文件在同一目录）
- [Python 获取 A 股历史日线：日期、排序与空数据检查](https://alphakit.cn/help/research/python-daily.html)
- [Python 合并行情与 PE/PB：日期对齐与缺失值处理](https://alphakit.cn/help/research/python-valuation.html)
- [历史分位怎么看：窗口、周期与样本](https://alphakit.cn/help/research/historical-percentiles.html)
- [AlphaKit 网页研究工具介绍](https://alphakit.cn/help/research/platform-overview.html)

## 版本说明

0.2.8 更新 SDK 说明、访问申请方式、官网与教程链接；数据查询方法与 0.2.7 相同。客户端版本与网站功能分别维护，可用范围以账户权限和页面说明为准。

## 错误处理

当前客户端会将连接失败、超时及 HTTP 错误响应包装为 `AlphaKitError(code=9999)`，包括 HTTP 401、403、429。因此，`9999` 不一定只表示网络故障。只有成功的 HTTP 响应包含非零业务码时，客户端才会保留该业务码。

| 服务端业务码 | 含义 | 处理方向 |
|---|---|---|
| 1001 | Token 无效、停用或过期 | 核对凭证状态 |
| 1002 | 当前账户无接口访问权限 | 联系管理方核对授权 |
| 1003 | IP 访问限制 | 核对网络环境和绑定数量 |
| 1004 | 触发限频 | 降低请求频率 |
| 1005 | 当日配额用尽 | 核对配额和恢复时间 |
| 1006 | 参数错误 | 核对接口、代码和日期 |
| 1500 | 服务端错误 | 稍后重试或联系管理方 |
| 9999 | 客户端请求失败或 HTTP 错误 | 检查连接、凭证、权限与限额 |

排查时可在本地查看 `exc.message`，联系管理方时提供发生时间、接口名及脱敏后的错误信息。不要发送真实 Token。
