Metadata-Version: 2.4
Name: alphakit-sdk
Version: 0.2.11
Summary: AlphaKit — Python A股、港股与美股数据客户端，支持行情、历史日线与覆盖查询
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,hong-kong-stocks,us-stocks,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：让数据进入研究，支持 Python A 股、港股与美股数据](https://alphakit.cn/assets/promotion/alphakit-sdk-hero-yahei-20261022.png)](https://alphakit.cn/help/sdk/quick-start.html)

AlphaKit SDK（包名 `alphakit-sdk`，导入名 `alphakit`）是 [AlphaKit](https://alphakit.cn/) 数据服务的 Python 客户端。A 股查询和港美股历史日线返回 `pandas.DataFrame`；港美股搜索、行情与覆盖查询返回包含元数据的字典，便于接入自己的研究流程。

客户端提供 A 股日线、每日估值、指数、ETF、申万行业、同花顺板块及部分市场行为数据查询；0.2.9 新增港股与美股证券搜索、单标的行情、历史日线和覆盖查询。具体接口、字段、历史范围和配额以服务端及账户权限为准。仅供个人学习与研究使用。

## 安装与申请访问

```bash
python -m pip install --upgrade alphakit-sdk
```

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

通过微信 **dfzzq719** 联系，申请时请注明：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 天的起止日期。研究和复现案例时，建议显式指定日期范围。

## 港股与美股：先查覆盖，再取历史日线

使用 0.2.9 或以上版本，显式配置 HTTPS 服务地址。AlphaKit 当前公共网关为 `https://alphakit.cn`；账户须有 SDK 服务权限及相应数据权限。

```python
import os
import alphakit as ak

api = ak.AlphaKit(
    token=os.environ["ALPHAKIT_TOKEN"],
    base_url="https://alphakit.cn",
)

# HK：五位证券代码；US：证券代码，如 AAPL、SPY。
coverage = api.overseas_coverage("US")
print(coverage["coverage"])

hk = api.overseas_daily("HK", "00700", since="20260101", to="20260930")
us = api.overseas_daily("US", "AAPL", since="20260101", to="20260929")
spy = api.overseas_daily("US", "SPY", since="20260101", to="20260929")
print(us.tail())
print(us.attrs["metadata"])  # 实际起止日期、完整日期边界与截断状态

securities = api.overseas_search("US", "AAPL")
quote = api.overseas_quote("US", "SPY", instrument="etf")
```

| 方法 | 返回 | 用途 |
|---|---|---|
| `overseas_search(market, keyword, limit=20)` | `dict` | 搜索已校验历史目录中的证券代码与已确认名称 |
| `overseas_quote(market, symbol, instrument="stock")` | `dict` | 单标的行情；ETF 显式传入 `instrument="etf"` |
| `overseas_daily(market, symbol, since=None, to=None, limit=2000)` | `DataFrame` | 单标的原始历史日线，股票及 ETF 使用相同方法 |
| `overseas_coverage(market, symbol=None)` | `dict` | 查询市场完整日期、可用日期、发布年份和已验证缓存数量 |

日线字段为 `trade_date`、`open`、`high`、`low`、`close`、`volume`。日期支持 `YYYYMMDD` 或 `YYYY-MM-DD`；`to` 省略时为当天，`since` 省略时为 `to` 所属年份的 1 月 1 日。因此，不传日期默认查询本年度。单次最多返回 2,000 行；超过 `limit` 时返回最近的记录，并在 `DataFrame.attrs["metadata"]` 中标记 `truncated`。空结果也保留元数据与股票状态。

历史日线目前只交付服务端已验证缓存中、市场 `complete_through` 边界以内的数据。`available_through` 之后或仅属部分更新的数据不会混入完整历史查询。跨年范围中的任一年缓存未就绪时返回 `AlphaKitError(code=503)`，不会静默缩短查询区间。`published_years` 表示数据源已发布年份，不表示 AlphaKit 已缓存全部年份；带 `symbol` 的覆盖查询默认只检查本年度。

2026-10-14 验证的腾讯（00700）、盈富基金（02800）日线截至 2026-09-30；苹果（AAPL）、SPY 截至 2026-09-29。最新覆盖以实际响应为准。价格为原始、不复权口径，缺失值保留；尚未核验交易日历，不承诺全市场、逐交易日完整性或历史成分覆盖。行情返回的数据时间与交易状态应一并检查，不承诺实时行情。

证券搜索基于最近完整年度的历史目录，名称仅覆盖此前经行情确认的代码，不是实时上市证券全集。查询沿用账户数据权限、IP 绑定、限频、每日配额及股票参与规则；本轮新增接口用于主动研究，保留资料并返回当前股票状态。

## A 股及现有查询方法

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

| 数据类别 | 方法示例 | 可以做什么 |
|---|---|---|
| 股票信息与日线 | `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/assets/promotion/alphakit-research-yahei-20261022.png)](https://alphakit.cn/help/research/platform-overview.html)

[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)

## 错误处理

港美股方法保留服务端 HTTP 错误码：401 表示凭证无效，403 表示权限或 IP 受限，409 表示查询期间股票参与规则发生变化，422 表示参数不符合要求，429 表示限频或额度限制，503 表示缓存未就绪、服务关闭或上游暂不可用。核对原因后再重试；客户端不自动重试。网络失败、超时或无法解析响应时使用 `code=9999`。

原有 A 股及通用查询方法仍将连接失败、超时和 HTTP 错误响应包装为 `AlphaKitError(code=9999)`，包括 HTTP 401、403、429。因此，`9999` 不一定只表示网络故障。只有成功的 HTTP 响应包含非零业务码时，这些方法才保留该业务码。

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

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