Metadata-Version: 2.4
Name: alphakit-sdk
Version: 0.2.15
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 股、港股与美股数据

**把行情、估值和行业数据接入 Python，让研究从一张可用的数据表开始。**

AlphaKit SDK 是 AlphaKit 数据服务的 Python 客户端，安装包名为 `alphakit-sdk`，导入名为 `alphakit`。A 股查询与港美股历史日线返回 `pandas.DataFrame`，查询后即可继续排序、合并、分析和保存；港美股搜索、行情及覆盖查询返回包含元数据的字典。

- **从价格走到估值：** 查询日线、PE、PB、市值与复权因子，按证券代码和日期整理研究样本。
- **把个股放回行业与市场：** 结合申万行业、同花顺板块、指数和 ETF 数据，为历史比较补充参照。
- **在同一个客户端研究不同市场：** 查询 A 股数据，以及港股、美股的证券目录、单标的行情和历史日线。

## 申请访问

通过微信 **dfzzq719** 联系，申请时请注明：SDK。

获取有效的 Token 和 HTTPS 数据服务地址后即可使用；申请时可了解数据范围、配额与使用条件。

## 可以查询什么

| 数据能力 | 适合怎样的研究 | 方法示例 |
|---|---|---|
| A 股基础信息与日线 | 查找证券资料，获取指定日期或区间的行情 | `stock_basic()`、`daily()` |
| 每日估值、复权与技术因子 | 将 PE、PB、市值与价格对齐，补充复权因子和技术因子 | `daily_basic()`、`adj_factor()`、`stk_factor()` |
| 行业与板块 | 按申万三级行业或同花顺板块组织研究分组，查看行业、板块走势与成分 | `sw_l1()`、`sw_l2()`、`sw_l3()`、`sw_daily()`、`sw_stock_industry()`、`ths_index()`、`ths_daily()`、`ths_member()` |
| 指数与 ETF | 用指数、ETF 行情作历史参照，补充净值、份额和主题资料 | `index_daily()`、`index_dailybasic()`、`etf_basic()`、`etf_daily()`、`etf_nav()`、`etf_share()`、`etf_theme_map()` |
| 资金流与市场行为 | 为量价研究补充资金流、两融、涨跌停、龙虎榜及停复牌信息 | `moneyflow()`、`moneyflow_dc()`、`margin()`、`margin_detail()`、`limit_list_d()`、`top_list()`、`hm_detail()`、`kpl_list()`、`suspend_d()` |
| 港股与美股 | 按代码查找研究标的，查询单标的行情、历史日线和数据覆盖范围 | `overseas_search()`、`overseas_quote()`、`overseas_daily()`、`overseas_coverage()` |
| 期权与通用查询 | 获取期权基础资料、日线，或调用服务端支持的其他数据接口 | `opt_basic()`、`opt_daily()`、`query()` |

可用接口、字段、历史范围和配额以接口说明及账户权限为准。仅供个人学习与研究使用。

## 几行代码，拿到第一份历史日线

需要 Python 3.8 或以上：

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

将凭证保存为环境变量 `ALPHAKIT_TOKEN` 和 `ALPHAKIT_BASE_URL`；在代码中读取环境变量，避免将 Token 写入公开代码、截图或仓库。

```python
import os
import alphakit as ak

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

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())
```

A 股日期使用 `YYYYMMDD`，证券代码带交易所后缀，如 `000001.SZ`、`600519.SH`。仅向 `daily()` 传入 `ts_code`、不带日期参数时，默认查询最近 365 天；为了复现研究，建议显式指定日期。

## 继续一步：把价格与 PE、PB 放进同一张表

沿用上面的客户端与日线结果，再查询同一证券、同一日期范围的估值数据：

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

if not df.empty and not valuation.empty:
    research = df.merge(
        valuation,
        on=["ts_code", "trade_date"],
        how="left",
        suffixes=("", "_valuation"),
    )
    print(research[["ts_code", "trade_date", "close", "pe", "pb"]].tail())
```

这样可以保留日线记录，并按交易日对齐 PE、PB；没有对应估值的日期保留为空值。实际字段以接口响应为准。行业映射可继续通过 `api.sw_stock_industry(ts_code="000001.SZ")` 查询，用于补充当前行业归属。

## 港股与美股：查覆盖、取日线、保留元数据

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

```python
# 沿用已配置 HTTPS 服务地址的 api。
coverage = api.overseas_coverage("US")
print(coverage["coverage"])

us = api.overseas_daily("US", "AAPL", since="20260101", to="20260630")
hk = api.overseas_daily("HK", "00700", 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")
```

港股使用五位证券代码，美股使用证券代码；ETF 单标的行情显式传入 `instrument="etf"`。历史日线字段为 `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` | 数据源的最新可用日期，部分更新的数据会在完整更新后纳入历史日线查询 |
| `published_years` | 数据源已发布的年份，具体可查询情况以服务端数据准备状态为准 |

指定 `symbol` 的覆盖查询默认查看本年度。跨年范围内任一年缓存未就绪时返回 `AlphaKitError(code=503)`，请稍后重试；接口不会因缓存缺失而省略该年份。返回元数据包含本次实际起止日期，便于核对研究区间。

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

证券搜索基于最近完整年度的历史目录，名称搜索仅覆盖已有名称信息的证券，目录范围可能与实时上市名单不同。查询遵循账户权限、IP 绑定、请求频率、每日配额及股票参与规则；研究查询保留资料并返回当前股票状态。

## 查询与错误处理

`query(api_name, **params)` 可调用服务端支持且账户有权访问的其他接口。`weekly`、`monthly`、`fina_indicator` 没有对应的专用客户端方法；通用查询的可用范围由服务端及账户权限决定。

```python
from alphakit.exceptions import AlphaKitError

try:
    result = api.stock_basic(ts_code="000001.SZ")
except AlphaKitError as exc:
    print(f"查询失败，错误码：{exc.code}")
```

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

A 股及通用方法将连接失败、超时和 HTTP 错误响应包装为 `AlphaKitError(code=9999)`，包括 HTTP 401、403、429。HTTP 请求成功、响应包含非零业务码时，保留该业务码：1001 为 Token 无效，1002 为无接口权限，1003 为 IP 限制，1004 为限频，1005 为当日配额用尽，1006 为参数错误，1500 为服务端错误。排查时结合错误消息、凭证、权限和配额检查，联系支持时提供发生时间、接口名与脱敏后的错误信息。

## 配套网页研究工具

![AlphaKit SDK 数据研究与配套 AlphaView 网页工具的真实 K 线界面](https://raw.githubusercontent.com/dfzzq719/docs/08aa78d3e21deddea3e100451f6a14c732448b9d/images/alphakit-sdk-saas-promo-20261022.webp)

图中为配套网页工具 AlphaView 的产品实景。Python SDK 提供数据查询接口，网页工具提供行情图表、技术指标与历史分位查看，具体范围按账户权限开放。

## 文档与联系

通过微信 **dfzzq719** 联系，申请时请注明：SDK。

[SDK 使用文档](https://alphakit.cn/help/sdk/quick-start.html) · [AlphaKit 官网](https://alphakit.cn/)
