stock-api-python

A股 / 港股 / 美股实时行情与 K 线数据接口，纯 Python 实现，仅依赖 requests。
一行代码拉取行情，多源自动兜底，开箱即用。

本项目是 @zhangxiangliang 的 stock-api（JavaScript/TypeScript 版）的 Python 移植，沿用了原版的接口设计与「多源自动兜底」思路。原版功能更为完整（自带 CLI、MCP Server、Web Demo，并已在 npm 发布），本库聚焦核心的行情与 K 线数据，方便在 Python 数据分析 / 量化场景中直接使用。感谢原作者的开源工作 🙏

English Documentation

特性

支持 A股 / 港股 / 美股：代码前缀 SH / SZ / HK / US，三个数据源均覆盖
多源自动兜底：默认 腾讯 → 东方财富 → 新浪，任一源失败自动切换
实时行情：单只 / 批量获取，支持股票搜索与数据源诊断（inspect）
K 线数据：日 / 周 / 月 / 分钟（腾讯、东方财富）
零门槛：仅依赖 requests，无需注册、无需 token

如果你需要用 Python 快速拉取行情和 K 线来做分析、写脚本、搭个人看盘工具，这个库适合你。

数据源支持情况

能力	腾讯	东方财富	新浪
实时行情（A / 港 / 美）	✅	✅	✅
K 线（日 / 周 / 月）	✅ 无频率限制	✅（日/周/月有节流，分钟稳定）	❌ 已下线
分钟 K 线（1/5/15/30/60m）	❌	✅ 稳定	❌
股票搜索	✅	✅	✅

说明：

三个数据源的实时行情均支持 A股、港股、美股，使用统一代码前缀 SH/SZ/HK/US 即可。
新浪的 K 线接口早年已下线，仅实时行情可用，且相对最容易触发限流，因此在本库的 Auto 中作为最后兜底。
网易接口已完全失效，代码中保留兼容壳类（NetEaseKline），调用时返回空列表、不影响其余逻辑。

Auto（实时行情）兜底顺序：腾讯 → 东方财富 → 新浪
AutoKline（K 线）兜底顺序：腾讯 → 东方财富

快速开始

git clone https://github.com/ng-fukgin/stock-api-python.git
cd stock-api-python
pip install -e .

三行代码获取实时行情

from stock_api.index import Auto

stock = Auto.get_stock("SH600519")          # 贵州茅台
print(f"{stock.name}: ¥{stock.now} ({stock.percent:+.2%})")

拉取 K 线并画图

from stock_api.stocks.kline import get_daily_kline

klines = get_daily_kline("SH600519", limit=120)  # 腾讯数据源，无频率限制
for k in klines[-5:]:
    print(f"{k.date}  开:{k.open:.2f}  收:{k.close:.2f}  高:{k.high:.2f}  低:{k.low:.2f}")

运行 python examples/candlestick.py 即可生成上方蜡烛图（含均线 + 成交量）。详见示例脚本。

安装

当前仅支持从源码安装（尚未发布到 PyPI）。

git clone https://github.com/ng-fukgin/stock-api-python.git
cd stock-api-python
pip install -e .

仅依赖 requests，无其他三方库。安装后可使用 stock-api 命令或 python -m stock_api.cli。

股票代码规范

统一使用 交易所前缀 + 股票代码 格式：

交易所	前缀	示例
上海交易所	`SH`	`SH600000`、`SH510500`
深圳交易所	`SZ`	`SZ000001`、`SZ300750`
香港交易所	`HK`	`HK00700`、`HK09988`
美国交易所	`US`	`USAAPL`、`USBABA`

实时行情

获取单只股票

from stock_api.index import Tencent, Eastmoney, Auto

# 指定数据源
stock = Tencent.get_stock("SH600000")
stock = Eastmoney.get_stock("SZ300750")

# 自动选择（推荐）
stock = Auto.get_stock("SH600519")
print(stock.to_dict())

获取多只股票（批量）

from stock_api.index import Tencent

stocks = Tencent.get_stocks(["SH600000", "SZ000651", "SH510500"])
for s in stocks:
    print(f"{s.name}: {s.now} ({s.percent:+.2%})")

美股 / 港股

from stock_api.index import Auto

aapl = Auto.get_stock("USAAPL")     # 苹果
tencent_hk = Auto.get_stock("HK00700")  # 腾讯控股
print(aapl.name, aapl.now, tencent_hk.name, tencent_hk.now)

搜索股票

from stock_api.index import Eastmoney

results = Eastmoney.search_stocks("贵州茅台")
for s in results:
    print(s.code, s.name)

inspect — 查看所有数据源状态

from stock_api.index import Auto

result = Auto.inspect_stock("SH600519")
# {
#   "code": "SH600519",
#   "source": "tencent",         # 实际使用的源
#   "stock": { ... },            # 股票数据
#   "sources": [                 # 各数据源详情
#     {"source": "tencent",   "status": "success", ...},
#     {"source": "eastmoney", "status": "success", ...},
#     {"source": "sina",      "status": "success", ...}
#   ]
# }

K 线数据

日 K 线

from stock_api.stocks.kline import get_daily_kline

# 自动选择数据源（腾讯 → 东方财富）
klines = get_daily_kline("SH600519")

# 指定数据源
klines = get_daily_kline("SH600519", source="tencent")    # 推荐，无频率限制
klines = get_daily_kline("SH600519", source="eastmoney")  # 日/周/月有节流

# 指定返回条数（默认 100）
klines = get_daily_kline("SH600519", limit=200)

每根 K 线结构：

{
  "date": "2024-05-20",
  "open": 1338.98,
  "close": 1308.00,
  "high": 1344.70,
  "low": 1296.87,
  "volume": 77148.0,
  "source": "tencent"
}

统一入口 `get_klines`（推荐）

如果你熟悉原版 stock-api 的 getKlines，本库提供了同形态的统一入口：按 period 选择周期、可选复权方式。各数据源类与 Tencent / Sina / Eastmoney / Auto 也都暴露了 get_klines(...) 方法。

from stock_api.stocks.kline import get_klines

# 日 K，不复权，取最近 120 根（默认值）
klines = get_klines("SH600519")

# 前复权 / 后复权
klines = get_klines("SH600519", period="day", adjust="qfq")
klines = get_klines("SH600519", period="day", adjust="hfq")

# 周 K / 月 K
klines = get_klines("SH600519", period="week", count=60)
klines = get_klines("SH600519", period="month", count=24)

# 分钟 K（仅东方财富支持）
klines = get_klines("SH600519", period="5m", count=100)

# 指定数据源
klines = get_klines("SH600519", source="tencent")

period：day / week / month / 1m / 5m / 15m / 30m / 60m
adjust：none（不复权，默认）/ qfq（前复权）/ hfq（后复权）
source：auto（默认）/ tencent / sina / eastmoney

说明：新浪 K 线接口已下线，source="sina" 时返回空列表；分钟 K 线仅东方财富支持。另可通过 from stock_api.index import get_sources, get_provider_capabilities 查询可用数据源与各自能力。

周 / 月 K 线

from stock_api.stocks.kline import get_weekly_kline, get_monthly_kline

weekly  = get_weekly_kline("SH600519")
monthly = get_monthly_kline("SH600519", source="tencent")

分钟 K 线

目前仅东方财富支持，稳定可用：

from stock_api.stocks.kline import get_minute_kline

# 支持周期：1m、5m、15m、30m、60m（默认 5m）
klines = get_minute_kline("SH600519", "5m")
klines = get_minute_kline("SH600519", "15m", limit=200)
klines = get_minute_kline("SH600519", "60m")

关于 limit 和起始日期：东方财富分钟 K 线返回的是截止当前时刻往前数 N 根 bar，没有固定起始日期，完全由 limit 参数控制。

直接使用数据源类

from stock_api.stocks.kline import EastmoneyKline, TencentKline

# 腾讯（日/周/月 K 线，无频率限制）
klines = TencentKline.get_daily_kline("SH600519", limit=50)
klines = TencentKline.get_weekly_kline("SH600519")

# 东方财富（日/周/月 K 线有节流；分钟 K 线稳定）
klines = EastmoneyKline.get_daily_kline("SH600519", limit=50)
klines = EastmoneyKline.get_minute_kline("SH600519", "30m", limit=100)

关于东方财富的频率限制

东方财富对实时行情与历史 K 线都有频控，本库的处理方式：

实时行情：改为一次性批量请求（多只股票拼到同一个 URL），并优先使用限流更宽松的 push2delay 域名，失败时自动退避重试。正常情况下不易触发限速。
历史 K 线（日 / 周 / 月）：接口本身对连续请求较敏感，代码内置 1~3 秒随机延迟 + 全局 Session 复用；若失败会自动重建 Session。

如果需要批量拉取多只股票的历史 K 线，优先使用腾讯数据源，无需等待：

codes = ["SH600000", "SH600519", "SZ000001", "SZ300750"]

from stock_api.stocks.kline import TencentKline
klines_map = {code: TencentKline.get_daily_kline(code, limit=250) for code in codes}

命令行工具（CLI）

安装源码后可用 stock-api 命令，或用 python -m stock_api.cli：

# 获取单只股票
stock-api get-stock SH510500

# 获取多只股票
stock-api get-stocks SH510500 SZ000651 SH600519

# 搜索股票
stock-api search 格力电器

# 获取 K 线（日/周/月/分钟，支持复权）
stock-api get-klines SH600519 --period day --count 120
stock-api get-klines SH600519 --period week --count 60 --source tencent
stock-api get-klines SH600519 --period 5m --count 100 --source eastmoney

# 指定数据源
stock-api get-stock SH600000 --source tencent
stock-api search 茅台 --source tencent

# 查看所有数据源状态
stock-api inspect-stock SH600519

输出均为格式化 JSON。

MCP Server（接入 AI 客户端）

本库自带一个 MCP server，可让支持 MCP 的 AI 客户端（Claude Code、Cursor、Cline 等）直接调用行情 / K 线 / 搜索 / 诊断能力——这也是原版 stock-api 被 AI 工具广泛使用的入口之一。

安装（可选依赖）

pip install -e ".[mcp]"

运行

python -m stock_api.mcp

在 AI 客户端中配置

{
  "mcpServers": {
    "stock-api": {
      "command": "python",
      "args": ["-m", "stock_api.mcp"]
    }
  }
}

把上面的 python 换成你实际使用的解释器路径（例如虚拟环境的 python 或绝对路径）。

提供的工具

工具	说明
`get_stock`	获取单只股票实时行情
`get_stocks`	批量获取股票实时行情
`get_klines`	获取 K 线（日/周/月/分钟，支持复权）
`search_stocks`	按关键词搜索股票
`inspect_stock`	诊断某只股票在各数据源的可用情况

数据结构

Stock（实时行情）

字段	类型	说明
`code`	str	股票代码（如 `SH600519`）
`name`	str	股票名称
`percent`	float	涨跌幅（小数，`0.0123` = +1.23%）
`now`	float	当前价格
`low`	float	今日最低价
`high`	float	今日最高价
`yesterday`	float	昨日收盘价
`source`	str	数据来源

Kline（K 线）

字段	类型	说明
`date`	str	日期（日 K: `2024-05-20`，分钟 K: `2024-05-20 09:30`）
`open`	float	开盘价
`close`	float	收盘价
`high`	float	最高价
`low`	float	最低价
`volume`	float	成交量（手）
`source`	str	数据来源

示例脚本

运行以下示例，快速体验本库能力：

示例	用途	运行命令
candlestick.py	绘制 K 线蜡烛图（含均线+成交量）	`python examples/candlestick.py`

示例依赖 matplotlib（可选）。首次运行前：pip install matplotlib

运行测试

pip install -e ".[test]"   # 或 pip install pytest
pytest tests/

tests/test_unit.py 为纯逻辑单测（不依赖网络）；tests/test_integration.py 为轻量实时冒烟测试，无网络时自动跳过。

Q：新浪 / 网易还能用吗？

网易：接口已完全失效，保留兼容壳类；新浪：K 线接口已下线（返回错误），但实时行情接口仍可用——A股、港股、美股均可返回数据，只是相对最容易触发限流，因此本库将其放在 Auto 兜底链的最后。建议优先使用腾讯或东方财富。

Q：东方财富还会被限速吗？

实时行情已通过「批量请求 + push2delay 域名 + 退避重试」大幅缓解，正常使用不易触发。历史 K 线（日/周/月）接口本身对连续请求较敏感，代码已内置随机延迟；如需批量拉历史 K 线，建议改用腾讯数据源。

Q：支持美股 / 港股吗？

支持。腾讯、东方财富、新浪三个数据源的实时行情都覆盖 A股、港股、美股，使用 HK / US 前缀即可（如 HK00700、USAAPL）。K 线方面，腾讯与东方财富支持 A/港/美股的日/周/月/分钟 K 线。

Q：数据可以商用吗？

本项目依赖各平台的公开行情接口，数据仅供学习和个人研究使用，请勿用于商业用途。各平台接口持续变化，如遇请求失败，优先切换到腾讯数据源，或查看项目页面是否有更新。

致谢

本项目的接口设计与多源兜底思路来自 @zhangxiangliang 的 stock-api，感谢他的开源工作 🎉

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
examples		examples
stock_api		stock_api
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
README_EN.md		README_EN.md
SKILL.md		SKILL.md
pyproject.toml		pyproject.toml
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation