Metadata-Version: 2.4
Name: alphakit-sdk
Version: 0.2.13
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://raw.githubusercontent.com/dfzzq719/docs/b7d96994f79276a6080b6ab84727c09cad6b433b/images/alphakit-sdk-hero-20261022.webp)](https://alphakit.cn/help/sdk/quick-start.html)

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

通过 SDK，可以查询 A 股日线、每日估值、指数、ETF、申万行业、同花顺板块及部分市场行为数据，也可以搜索港股与美股证券、获取单标的行情和历史日线、查看数据覆盖范围。可用接口、字段、历史范围和配额以接口说明及账户权限为准。仅供个人学习与研究使用。

## 安装与申请访问

```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="20260630")
us = api.overseas_daily("US", "AAPL", since="20260101", to="20260630")
spy = api.overseas_daily("US", "SPY", since="20260101", to="20260630")
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`。空结果也保留元数据与股票状态。

查询前，可通过 `overseas_coverage()` 了解数据范围：`complete_through` 是历史日线的完整更新截止日期，`available_through` 是数据源的最新可用日期。历史日线按 `complete_through` 范围返回，部分更新的数据会在完整更新后纳入查询。`published_years` 列出数据源已发布的年份，各年份的可查询情况以服务端数据准备状态为准。指定 `symbol` 时，覆盖查询默认查看本年度。

跨年查询需要所选年份的数据均已就绪；任一年仍在准备时，接口返回 `AlphaKitError(code=503)`，请稍后重试。接口不会因某一年暂不可用而省略该年份。返回元数据包含实际起止日期，可用于核对本次查询范围。

价格采用原始、不复权口径，缺失值按原样保留。历史数据按证券的实际可用记录提供；覆盖日期表示数据更新进度，不能直接推定全市场、逐交易日或历史成分覆盖。行情请结合响应中的数据时间和交易状态使用，时效以返回时间为准。

证券搜索基于最近完整年度的历史目录，适合按代码查找研究标的；名称搜索仅覆盖已有名称信息的证券。该目录与实时上市名单的范围可能不同。所有查询遵循账户数据权限、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("接口名", **参数)` 调用；通用方法不会自动增加数据权限。

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

[![AlphaView 产品实景：上证指数日K、布林带、筹码分布及多项技术指标](https://raw.githubusercontent.com/dfzzq719/docs/b7d96994f79276a6080b6ab84727c09cad6b433b/images/alphaview-product-20261022.webp)](https://alphakit.cn/help/research/platform-overview.html)

AlphaView 产品画面：在同一视图中观察日K、布林带、筹码分布、技术指标与历史分位。

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