# Global Stock Data > 美股港股全栈数据工具包（官方源优先）— 十三层架构·30+端点·11数据源·全部零鉴权。在原有行情/K线/技术指标(MA/MACD/RSI/KDJ/布林带)/基本面/资金面/期权/SEC Filing/工具八层之上，新增：CBOE官方期权链(完整希腊字母+IV+0DTE流+异动识别)、FINRA全市场每日空头成交量、SEC EDGAR申报事件流(Form4内部人/8-K/13F机构持仓)、EDGAR全市场横截面筛选、美债收益率曲线/CFTC COT/财报日历。每个数据源标注合规级别与条款原文。内嵌全部调用代码，自包含零依赖外部文件。适用于美股港股个股分析、全市场筛选、财报解读、期权与0DTE策略、做空数据追踪、SEC文件检索、资金流与机构持仓分析等场景。 - Skill: `simonlin1212/global-stock-data` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add simonlin1212/global-stock-data` - Raw SKILL.md: https://api.skillmd.com/api/skills/simonlin1212/global-stock-data/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: simonlin1212 (https://skillmd.com/u/simonlin1212) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/simonlin1212/global-stock-data --- > 📦 项目主页：https://github.com/simonlin1212/global-stock-data — 更新、反馈、支持作者 > > 作者：Simon 林 · X [@linsizhen](https://x.com/linsizhen) · 邮箱：simonlin0423@gmail.com # 美股港股全栈数据工具包 V2.0 — 官方源优先 十三层数据架构，30+ 个端点，11 个数据源，全部零鉴权，实测可用（2026-07-24 全量回归验证）。 **V2.0 设计原则：官方源优先。** 新增层的主力数据取自美国政府（SEC EDGAR / Treasury / CFTC）、 自律组织（FINRA）与交易所（CBOE / Nasdaq）的公开端点。**每个数据源都标注了合规级别与条款原文** （见下方「数据源合规分级」）——"官方"不等于"可自由使用"，各源差异极大。 **本工具只分发代码，不分发、不转售任何市场数据**；数据由使用者自行按各源条款获取。 **使用方式：** 将本文件放入 `~/.claude/skills/global-stock-data/SKILL.md`，Claude Code 会自动识别并在美股/港股相关对话中激活。 ``` 行情层（实时/延时） ├── 新浪财经 → 美股 gb_XXXX 36字段 / 港股 rt_hkXXXXX 25字段 ├── 腾讯财经 → 美股 usXXXX 71字段 / 港股 r_hkXXXXX 78字段 └── 东财 push2 → 美股/港股 secid 实时行情，含中文名/涨跌幅/换手率 K线层（日/周/月/分钟） ├── 新浪 → 美股日K (回溯至1984年) └── Yahoo chart → 美股+港股 (v8 API, 零crumb) 技术指标层（纯计算，零额外依赖） └── MA/EMA + MACD + RSI + KDJ + 布林带 基于K线OHLCV，纯Python计算 基本面层 ├── 东财 datacenter → 美股/港股三表(资产负债+利润+现金流) + GMAININDICATOR(关键指标) ├── Yahoo crumb → 23个模块(财务数据+关键指标+分析师+机构持仓) └── SEC EDGAR XBRL → 美股503个GAAP指标 (仅美股) 资金面层 └── 东财 push2his → 日级资金流(主力/大单/中单/小单) 美股+港股 期权层（仅美股） └── Yahoo crumb → 期权链(calls+puts, 所有到期日) 仅美股(港股期权不在Yahoo覆盖范围) SEC Filing层（仅美股） ├── EDGAR submissions → 10-K/10-Q/8-K 完整Filing列表 └── EDGAR XBRL → 结构化财务指标(营收/净利/EPS等) 工具层 ├── 东财 search → 股票搜索(中英文, 含市场代码映射) ├── 东财 push2 → 全市场股票列表(涨跌幅/成交量排名, 美股5925只+港股18000+只) ├── Yahoo search → 新闻资讯(按股票代码) └── SEC CIK mapping → ticker↔CIK 映射 (仅美股) ━━━ 以下为 V2.0 新增（官方源优先）━━━ 期权层·CBOE 官方（仅美股）⭐ └── CBOE cdn → 全链 + IV + delta/gamma/vega/theta/rho + 0DTE + 异动flow [C级·需授权] 做空层（仅美股）⭐ └── FINRA Reg SHO → 全市场每日空头成交量(实测12,112只) + 个股时序 + 排行 [B级] 申报事件流（仅美股）⭐ ├── EDGAR 每日索引 → Form4内部人/8-K/13F机构持仓/144，当日全量 [S级] └── EDGAR 全文检索 → 2001至今所有申报正文，按关键词+表单+日期 [S级] 全市场横截面（仅美股）⭐ └── EDGAR frames → 任意XBRL标签一次拿全市场(实测1,842~5,309家)=免费screener [S级] 宏观 / 日历 ⭐ ├── Treasury → 美债收益率曲线(1M~30Y, 每日) [S级] ├── CFTC → COT 持仓报告 [S级] └── Nasdaq → 财报日历(含盘前盘后+EPS预期) [C级·未核实] ``` --- ## 端点路由速查（按需定位，不必通读全文） | 我想要… | 去哪层 | 主力源 | 合规级 | |---|---|---|---| | 实时/延时报价 | Layer 1 | 新浪 / 腾讯 / 东财 | C | | K 线（日/周/月） | Layer 2 | 新浪 / Yahoo | C | | 技术指标 MA/MACD/RSI/KDJ/布林 | Layer 3 | 本地计算 | — | | 财报三表 / 关键指标 / 分析师 / 机构持仓 | Layer 4 | 东财 / Yahoo / EDGAR | C·S | | 日级资金流 | Layer 5 | 东财 | C | | **期权链 + 希腊字母 + IV + 0DTE + 异动flow** | **Layer 6.1** | **CBOE 官方** ⭐ | C | | 期权链（无希腊字母，后备） | Layer 6.2 | Yahoo | C | | 10-K/10-Q/8-K 列表、XBRL 财务 | Layer 7 | SEC EDGAR | **S** | | 搜索 / 新闻 / CIK 映射 / 全市场列表 | Layer 8 | 东财 / Yahoo / SEC | C·S | | **全市场每日空头成交量、个股空头占比** | **Layer 9** | **FINRA Reg SHO** ⭐ | B | | **当日申报流：Form 4 内部人 / 8-K / 13F** | **Layer 10.1** | **EDGAR 每日索引** ⭐ | **S** | | **申报全文检索（2001 至今正文）** | **Layer 10.2** | **EDGAR FTS** ⭐ | **S** | | **全市场基本面横截面（免费 screener）** | **Layer 11** | **EDGAR frames** ⭐ | **S** | | 美债收益率曲线 / CFTC COT / 财报日历 | Layer 12 | Treasury / CFTC / Nasdaq | S·C | ⭐ = V2.0 新增，且为 yfinance 与多数开源方案不具备的能力。 --- ## 数据源合规分级（取用前必读 — 各级均引条款原文） > 下表结论来自 **2026-07-24 逐家实读各源条款原文**，不是推断。引号内为原文。 > **各源差异极大，"官方"不等于"可自由使用"。** ### S 级 — 可自由使用（含商用与再分发） | 源 | 依据（原文） | |---|---| | **SEC EDGAR** | 官网明示：*"Anyone can access and download this information **for free**"*、*"We **allow scripted access** to sec.gov content"*。**硬性要求**：`Current max request rate: 10 requests/second`，且必须声明 User-Agent（格式 `Company Name AdminContact@domain.com`），否则触发 *"Undeclared Automated Tool"* / Access Denied | | **US Treasury / CFTC** | 美国联邦政府作品不受版权保护（17 U.S.C. §105）。⚠️ 本次**未逐条核验**两站条款正文，按政府数据惯例归此级 | ### B 级 — 数据文件系主动公开，但站点条款含限制 | 源 | 依据（原文） | |---|---| | **FINRA** | Reg SHO 每日文件是 FINRA 主动发布供下载的监管披露文件；但其 Terms of Use 同时禁止 *"use any process to monitor or copy the FINRA Website **in bulk**, or use any **data mining, scraping or harvesting tools (including robots)**"*，且站点声明 *"FINRA Data provides **non-commercial use** of data"*。→ **下载已发布的数据文件属常规用法；批量爬站点页面不属于。商用前请自行向 FINRA 确认。** | ### C 级 — 使用需事先授权，或条款未核实 | 源 | 依据（原文） | |---|---| | **CBOE** | Use of Content 政策：使用任何 Cboe Content 须 *"receive **approval in advance** from Cboe"*，并须 *"**execution of a license agreement**"*；政策**不区分**商用/非商用、不区分实时/延时。→ **本工具的 CBOE 期权层仅供个人研究；商业用途或再分发前，须先向 Cboe 申请授权。** | | **Nasdaq** | 本次抓取条款页超时，**未核实**。按未核实处理 | | Yahoo / 东财 / 新浪 / 腾讯 | Yahoo 官方文档写明 **personal use only**；其余为站点前端接口。仅供个人研究，勿用于商业产品或再分发 | ### ⛔ 已排除的源 | 源 | 原因 | |---|---| | **HKEX（CCASS 港股席位持股）** | 其 Terms of Use 明文禁止 *"any '**robot**', '**bot**', '**spider**', '**scraper**' or other automated device... to access, obtain, copy, monitor or republish any portion of the Website"*，禁止 *"text or data mining or web scraping"*，且适用于 *"**whether or not for gain**"*（不论是否营利）。→ **本工具不提供 CCASS 抓取代码。** 需要港股席位持股/南向资金数据者，请通过 HKEX 授权渠道或其网页人工查询 | ### 给使用者的三条硬规则 1. **商业用途**：只依赖 **S 级**（SEC EDGAR / Treasury / CFTC）。B 级需自行确认，C 级须先取得授权。 2. **再分发**：本工具**只分发代码，不分发任何市场数据**。你也不应把 B/C 级源取得的数据对外分发。 3. **限速**：所有新增层的请求已内置节流（见「统一 HTTP 层」）。**不要绕过它**——SEC 的 10 req/s 是官方硬上限。 --- ## When to Activate - 用户要查**美股/港股**行情（价格/涨跌幅/成交量） - 用户要拉 K 线（日线/周线/月线/分钟线） - 用户要看**财报**（资产负债表/利润表/现金流量表） - 用户要看**关键财务指标**（PE/PB/ROE/利润率/目标价） - 用户要看**分析师预期**（EPS预测/评级/目标价区间） - 用户要看**机构持仓**（前十大机构/持股比例） - 用户要看**资金流向**（主力/大单/中单/小单净流入） - 用户要查**期权链**（calls/puts/到期日/Greeks） - 用户要查 **SEC Filing**（10-K/10-Q/8-K/年报/季报） - 用户要做**美股财报量化分析**（从 XBRL 拉多年营收/净利/EPS 趋势） - 用户要**搜索股票**（中英文均可） - 用户要看**美股/港股新闻** - 用户要看**全市场涨跌幅排名**（当日涨幅/跌幅最大的股票） - 用户要做**全市场筛选**（遍历美股/港股列表做初筛） - 用户要看**关键财务指标概览**（营收/净利/EPS/ROE/ROA/资产负债率 中文版） - 用户要看**技术指标**（MACD/RSI/KDJ/布林带/均线） - 用户要判断**金叉死叉/超买超卖/变盘信号** - 关键词：美股、港股、AAPL、苹果、腾讯、00700、TSLA、特斯拉、BABA、阿里巴巴、行情、K线、财报、PE、PB、ROE、分析师、目标价、期权、call、put、SEC、10-K、年报、季报、资金流、主力、机构持仓、新闻、涨幅排名、全市场、筛选、关键指标、MACD、RSI、KDJ、布林带、均线、金叉、死叉、超买、超卖、技术分析 --- ## Prerequisites ```bash pip install requests ``` | 依赖 | 版本要求 | 用途 | |------|---------|------| | requests | any | 所有 HTTP API 直连 | > **极简依赖：** 仅需 requests，所有数据源均为直连 HTTP API，零第三方数据封装。 --- ## 市场代码规则 ### 东财 secid 前缀（push2/push2his 用） | 前缀 | 市场 | 示例 | |------|------|------| | 105 | 美股 NASDAQ | `105.AAPL`, `105.TSLA` | | 106 | 美股 NYSE | `106.BABA`, `106.JD` | | 107 | 美股 ETF/其他 | `107.CRSH` | | 116 | 港股 | `116.00700`, `116.09988` | > **如何判断 105/106/107？** 调 `stock_search()` 获取 `MktNum` 字段自动映射。 ### Yahoo Finance 代码格式 | 市场 | 格式 | 示例 | |------|------|------| | 美股 | 直接 ticker | `AAPL`, `TSLA`, `BABA` | | 港股 | 四/五位数字 + `.HK` | `0700.HK`, `9988.HK` | ### 东财 datacenter SECUCODE 格式 | 市场 | 格式 | 示例 | |------|------|------| | 美股 NASDAQ | `TICKER.O` | `AAPL.O`, `TSLA.O` | | 美股 NYSE | `TICKER.N` | `BABA.N`, `JD.N` | | 港股 | `CODE.HK` | `00700.HK`, `09988.HK` | --- ## 共用 Helper 函数 ### Yahoo Finance crumb 管理器 Yahoo quoteSummary/options 等 v7/v10 接口需要 cookie+crumb。以下 helper 自动获取并缓存： ```python import requests _yahoo_session = None def get_yahoo_session() -> requests.Session: """获取带 crumb 的 Yahoo Finance session（自动缓存）""" global _yahoo_session if _yahoo_session and hasattr(_yahoo_session, '_crumb'): return _yahoo_session s = requests.Session() s.headers['User-Agent'] = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36' # Step 1: 获取 cookie s.get('https://fc.yahoo.com', timeout=10) # Step 2: 获取 crumb r = s.get('https://query2.finance.yahoo.com/v1/test/getcrumb', timeout=10) r.raise_for_status() s._crumb = r.text _yahoo_session = s return s def yahoo_quote_summary(symbol: str, modules: list[str]) -> dict: """Yahoo quoteSummary 统一查询""" s = get_yahoo_session() r = s.get(f'https://query2.finance.yahoo.com/v10/finance/quoteSummary/{symbol}', params={ 'modules': ','.join(modules), 'crumb': s._crumb, }, timeout=15) r.raise_for_status() results = r.json().get('quoteSummary', {}).get('result', [{}]) return results[0] if results else {} ``` ### 东财数据中心统一查询 ```python UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" DATACENTER_URL = "https://datacenter-web.eastmoney.com/api/data/v1/get" def eastmoney_datacenter(report_name: str, columns: str = "ALL", filter_str: str = "", page_size: int = 50, sort_columns: str = "", sort_types: str = "-1") -> list[dict]: """东财数据中心统一查询""" params = { "reportName": report_name, "columns": columns, "filter": filter_str, "pageNumber": "1", "pageSize": str(page_size), "sortColumns": sort_columns, "sortTypes": sort_types, "source": "WEB", "client": "WEB", } r = requests.get(DATACENTER_URL, params=params, headers={"User-Agent": UA}, timeout=15) d = r.json() if d.get("result") and d["result"].get("data"): return d["result"]["data"] return [] ``` --- ### 官方源统一出口（限流 + UA 声明）— V2.0 新增 V2.0 新增的 Layer 9–12 全部走这个出口。它负责三件事：**按源限速**、**SEC User-Agent 声明**、 **友好错误提示**。 > ⚠️ **使用前必改**：把 `SEC_CONTACT` 换成你自己的真实姓名与邮箱。 > SEC 官方要求声明 User-Agent，未声明会被判定为 *Undeclared Automated Tool* 并拒绝服务。 ```python import requests, time, threading # ⚠️⚠️ 必改：SEC 要求 UA 含真实联系方式，格式 "Company Name AdminContact@domain.com" SEC_CONTACT = "your-name your-email@example.com" class DataNotAvailable(RuntimeError): """该日/该标的确实没有数据（如非交易日、文件尚未发布）——可安全回退到下一个候选日。 与配置错误、网络错误区分开：后者必须立刻抛给调用方， 否则「SEC_CONTACT 没配」会被日期回退循环吞掉，最后伪装成「没找到数据」。 """ class _RateLimiter: """线程安全的最小间隔节流器（用锁，避免并发下被击穿）""" def __init__(self, max_per_sec: float): self._interval = 1.0 / float(max_per_sec) self._last = 0.0 self._lock = threading.Lock() def wait(self) -> None: with self._lock: gap = self._interval - (time.monotonic() - self._last) if gap > 0: time.sleep(gap) self._last = time.monotonic() # 各源限速：SEC 官方硬上限 10/s，此处取 8/s 留余量；其余为自律保护值 _LIMITS = { "sec.gov": _RateLimiter(8), "finra.org": _RateLimiter(4), "cboe.com": _RateLimiter(4), "nasdaq.com": _RateLimiter(2), "_default": _RateLimiter(5), } def _limiter_for(url: str) -> _RateLimiter: for host, lim in _LIMITS.items(): if host != "_default" and host in url: return lim return _LIMITS["_default"] def _is_object_missing(resp) -> bool: """ 正向识别「资源确实不存在」。 ⚠️ SEC Archives 与 FINRA CDN 都托管在 S3 上，而 S3 在调用方没有 ListBucket 权限时，对**不存在的对象**返回 `403 AccessDenied`（XML） 而不是 404 NoSuchKey。实测 2026-07-24 两个源行为一致。 真正的拒绝长得完全不同（SEC 的 UA 未声明返回 ~4.8KB HTML 页面）， 所以这里按 Content-Type + XML 错误码正向判定， 而不是用「排除法」——否则限流/封禁会被伪装成「没数据」。 """ if resp.status_code == 404: return True if resp.status_code != 403: return False ctype = (resp.headers.get("Content-Type") or "").lower() head = (resp.text or "")[:500] return "xml" in ctype and "AccessDenied" in head def official_get(url: str, params: dict = None, headers: dict = None, timeout: int = 30, as_json: bool = False): """ V2.0 官方源统一出口：自动节流 + UA 处理 + 友好错误。 as_json=True 返回 dict，否则返回 str。 异常语义：资源不存在 → DataNotAvailable（调用方可回退到下一个候选日）； 配置/限流/网络 → RuntimeError（必须冒泡）。 """ if "sec.gov" in url: if "your-email@example.com" in SEC_CONTACT: raise RuntimeError( "请先把 SEC_CONTACT 改成你的真实姓名与邮箱 —— SEC 要求声明 " "User-Agent，否则返回 Undeclared Automated Tool 错误。") h = {"User-Agent": SEC_CONTACT, "Accept-Encoding": "gzip, deflate"} else: h = {"User-Agent": UA} h.update(headers or {}) _limiter_for(url).wait() try: r = requests.get(url, params=params, headers=h, timeout=timeout) r.raise_for_status() except requests.HTTPError as e: resp = e.response code = resp.status_code low = (resp.text or "")[:4000].lower() # ① 正向识别：资源确实不存在（404，或 S3 风格的 403 AccessDenied） if _is_object_missing(resp): raise DataNotAvailable( f"HTTP {code} {url[:80]} — 资源不存在（该日无数据/尚未发布）") from e # ② SEC 的 UA 未声明（返回 HTML 页，含 Undeclared Automated Tool） if code == 403 and "undeclared" in low: raise RuntimeError( f"SEC 拒绝请求：User-Agent 未被识别为已声明。" f"当前 SEC_CONTACT={SEC_CONTACT!r}，" f"格式应为 'Company Name AdminContact@domain.com'") from e # ③ 其余一律视为真错误，必须冒泡（限流/封禁/权限/接口变更） hint = {403: "被拒绝：限流、封禁或权限问题（已排除「资源不存在」）", 404: "端点不存在：接口可能已变更", 429: "请求过快：已内置节流，若仍触发请调低 _LIMITS"}.get(code, "") raise RuntimeError(f"HTTP {code} {url[:80]} — {hint}") from e except requests.RequestException as e: raise RuntimeError(f"请求失败 {url[:80]} — {type(e).__name__}: {e}") from e return r.json() if as_json else r.text # ── 异常约定（V2.0）── # DataNotAvailable : 该日/该标的确实没有数据（非交易日、文件未发布、标的无期权…） # → 调用方可安全回退到下一个候选日 # RuntimeError : 配置错误（SEC_CONTACT 未改）、限流、网络故障 # → 必须冒泡给使用者，不可伪装成「没数据」 # ValueError : 参数错误（如把港股代码传给仅支持美股的层） def assert_us_ticker(ticker: str) -> str: """Layer 6.1 / 9 / 10 / 11 仅支持美股；传入港股代码时给出明确提示""" t = str(ticker).upper() if t.endswith(".HK") or (t.isdigit() and len(t) in (4, 5)): raise ValueError(f"'{ticker}' 看起来是港股代码；该层仅支持美股。" f"港股请用 Layer 1-5 的港股端点。") if not t.replace(".", "").replace("-", "").isalnum(): raise ValueError(f"无效的 ticker: '{ticker}'") return t ``` > `requests` 会自动解压 gzip 响应，因此上面带 `Accept-Encoding` 是安全的。 > 若你改用 `urllib` 自行实现，**必须手动 `gzip.decompress`**，否则 SEC 返回的内容会解析失败。 --- ## Layer 1: 行情层 ### 1.1 美股实时行情 — 新浪 + 腾讯 两个独立数据源，任一可用即可。新浪字段侧重价格成交，腾讯字段更全（含52周高低/市值/PE）。 ```python import requests, re def us_stock_quote_sina(ticker: str) -> dict: """ 新浪美股行情 — 36字段 ticker: 纯字母，如 "AAPL", "TSLA", "BABA" """ url = f"https://hq.sinajs.cn/list=gb_{ticker.lower()}" r = requests.get(url, headers={ "Referer": "https://finance.sina.com.cn/", "User-Agent": UA, }, timeout=10) r.encoding = "gbk" text = r.text m = re.search(r'"(.+)"', text) if not m: return {} fields = m.group(1).split(",") if len(fields) < 30: return {} return { "name": fields[0], # 中文名 "price": float(fields[1]), # 最新价 "change_pct": float(fields[2]), # 涨跌幅 % "timestamp": fields[3], # 时间 "prev_close": float(fields[26]), # 昨收 "open": float(fields[5]), # 开盘 "high": float(fields[6]), # 最高 "low": float(fields[7]), # 最低 "volume": float(fields[10]) if fields[10] else 0, # 成交量 "high_52w": float(fields[8]) if fields[8] else 0, # 52周最高 "low_52w": float(fields[9]) if fields[9] else 0, # 52周最低 "market_cap": float(fields[12]) if fields[12] else 0, # 市值 "eps": float(fields[13]) if fields[13] else 0, # EPS "pe": float(fields[14]) if fields[14] else 0, # PE } def us_stock_quote_tencent(ticker: str) -> dict: """ 腾讯美股行情 — 71字段 ticker: 纯字母，如 "AAPL" """ url = f"https://qt.gtimg.cn/q=us{ticker.upper()}" r = requests.get(url, timeout=10) r.encoding = "gbk" text = r.text m = re.search(r'"(.+)"', text) if not m: return {} fields = m.group(1).split("~") if len(fields) < 52: # 需读到 fields[51](PB)，美股正常返回 71 个 return {} # ⚠️ 下标以实测为准，勿照抄港股那套（两市布局不同，见本节末「腾讯行情字段对照表」） return { "name": fields[1], # 中文名 "name_en": fields[46], # 英文名，如 "Apple Inc." "price": float(fields[3]) if fields[3] else 0, "prev_close": float(fields[4]) if fields[4] else 0, "open": float(fields[5]) if fields[5] else 0, "volume": int(float(fields[6])) if fields[6] else 0, "high": float(fields[33]) if fields[33] else 0, "low": float(fields[34]) if fields[34] else 0, "high_52w": float(fields[48]) if fields[48] else 0, "low_52w": float(fields[49]) if fields[49] else 0, "change_pct": float(fields[32]) if fields[32] else 0, "float_market_cap": float(fields[44]) if fields[44] else 0, # 流通市值，亿美元 "market_cap": float(fields[45]) if fields[45] else 0, # 总市值，亿美元 "eps": float(fields[47]) if fields[47] else 0, "pe": float(fields[39]) if fields[39] else 0, "pb": float(fields[51]) if fields[51] else 0, "currency": fields[35], # "USD" "timestamp": fields[30], } ``` ### 1.2 港股实时行情 — 腾讯 + 新浪 ```python def hk_stock_quote_tencent(code: str) -> dict: """ 腾讯港股行情 — 78字段（最全） code: 五位数字，如 "00700", "09988" """ url = f"https://qt.gtimg.cn/q=r_hk{code}" r = requests.get(url, timeout=10) r.encoding = "gbk" text = r.text m = re.search(r'"(.+)"', text) if not m: return {} fields = m.group(1).split("~") if len(fields) < 76: # 需读到 fields[75](币种)，港股正常返回 78 个 return {} # ⚠️ 下标以实测为准，与美股那套不同（见本节末「腾讯行情字段对照表」） return { "name": fields[1], # 中文名 "code": fields[2], # 五位代码，如 "00700"（旧版误当英文名） "name_en": fields[46], # 英文名，如 "TENCENT" "price": float(fields[3]) if fields[3] else 0, "prev_close": float(fields[4]) if fields[4] else 0, "open": float(fields[5]) if fields[5] else 0, "high": float(fields[33]) if fields[33] else 0, "low": float(fields[34]) if fields[34] else 0, "volume": int(float(fields[6])) if fields[6] else 0, # 成交量(股) "amount": float(fields[37]) if fields[37] else 0, # 成交额 "change_pct": float(fields[32]) if fields[32] else 0, "pe": float(fields[39]) if fields[39] else 0, "pb": float(fields[58]) if fields[58] else 0, "high_52w": float(fields[48]) if fields[48] else 0, "low_52w": float(fields[49]) if fields[49] else 0, "float_market_cap": float(fields[44]) if fields[44] else 0, # 流通市值，亿港元 "market_cap": float(fields[45]) if fields[45] else 0, # 总市值，亿港元 "currency": fields[75], # "HKD" "timestamp": fields[30], } def hk_stock_quote_sina(code: str) -> dict: """ 新浪港股行情 — 25字段 code: 五位数字，如 "00700" """ url = f"https://hq.sinajs.cn/list=rt_hk{code}" r = requests.get(url, headers={ "Referer": "https://finance.sina.com.cn/", "User-Agent": UA, }, timeout=10) r.encoding = "gbk" text = r.text m = re.search(r'"(.+)"', text) if not m: return {} fields = m.group(1).split(",") if len(fields) < 15: return {} return { "name_en": fields[0], "name": fields[1], # 中文名 "open": float(fields[2]) if fields[2] else 0, "prev_close": float(fields[3]) if fields[3] else 0, "high": float(fields[4]) if fields[4] else 0, "low": float(fields[5]) if fields[5] else 0, "price": float(fields[6]) if fields[6] else 0, "change": float(fields[7]) if fields[7] else 0, "change_pct": float(fields[8]) if fields[8] else 0, "volume": float(fields[12]) if fields[12] else 0, "amount": float(fields[11]) if fields[11] else 0, } ``` #### 腾讯行情字段对照表（`qt.gtimg.cn` · 2026-07-26 实测校准） ⚠️ **美股与港股的字段布局不同，不能共用一套下标。** 美股返回 71 个字段，港股 78 个。 下面每个下标都以真实响应逐个核对过（`usAAPL` / `hk00700`），网上流传的映射表多处有误。 | 含义 | 美股下标 | 港股下标 | 实测值（AAPL / 00700） | |---|---|---|---| | 中文名 | 1 | 1 | 苹果 / 腾讯控股 | | 代码 | 2 | 2 | AAPL.OQ / 00700 | | **英文名** | **46** | **46** | Apple Inc. / TENCENT | | 现价 | 3 | 3 | 333.02 / 434.600 | | 昨收 / 今开 | 4 / 5 | 4 / 5 | — | | 成交量 | 6 | 6 | ⚠️ 港股带小数位（`22959603.0`），必须 `int(float(x))` | | 涨跌幅 % | 32 | 32 | 3.53 / -2.38 | | 当日最高 / 最低 | 33 / 34 | 33 / 34 | — | | **币种** | **35** | **75** | USD / HKD | | **PE** | **39** | **39** | 40.32 / 15.87 | | **流通市值**（亿本币） | **44** | **44** | 48881.62 / 39516.08 | | **总市值**（亿本币） | **45** | **45** | 48911.83 / 39516.08 | | EPS | 47 | — | 8.26（333.02 ÷ 8.26 = 40.32 ✓ 与 PE 自洽） | | **52 周最高 / 最低** | **48 / 49** | **48 / 49** | 334.99·200.72 / 677.7·411.0 | | **PB** | **51** | **58** | 45.93 / 3.14 | **市值单位是「亿本币」，不是股数**：AAPL 总市值 48911.83（亿美元）= 现价 333.02 × 总股本 14,687,356,000，可用 `fields[62]` 的总股本反算核对。港股同理，单位为亿港元。 **自行复现命令**（行号 N ↔ 数组下标 N−1）： ```bash curl -s "https://qt.gtimg.cn/q=usAAPL" | iconv -f GBK -t UTF-8 | tr '~' '\n' | cat -n curl -s "https://qt.gtimg.cn/q=hk00700" | iconv -f GBK -t UTF-8 | tr '~' '\n' | cat -n ``` > 港股 `hk` 与 `r_hk` 两种前缀返回的字段布局完全一致（均 78 个），可互换。 > 感谢 [@HoRiZonn0](https://github.com/HoRiZonn0) 在 issue #2 中提供的完整对照，本表据此逐条复测后修订。 ### 1.3 东财 push2 实时行情 — 美股 + 港股 东财 push2 接口，通过 secid 统一查询美股/港股实时行情。优点：有中文名、换手率、涨跌幅，且 secid 可由 `stock_search()` 自动获取。 ```python def stock_quote_eastmoney(ticker_or_code: str, secid_prefix: int = 105) -> dict: """ 东财 push2 实时行情 — 美股+港股统一接口 美股: stock_quote_eastmoney("AAPL", 105) # NASDAQ stock_quote_eastmoney("BABA", 106) # NYSE 港股: stock_quote_eastmoney("00700", 116) 返回: 最新价/开高低收/成交量/成交额/换手率/涨跌幅/中文名 secid_prefix 说明: 105=NASDAQ, 106=NYSE, 107=US_ETF, 116=港股 如不确定前缀，先调 stock_search() 获取 mkt_num """ url = "https://push2.eastmoney.com/api/qt/stock/get" params = { "secid": f"{secid_prefix}.{ticker_or_code}", "fields": "f43,f44,f45,f46,f47,f48,f55,f57,f58,f59,f60,f170", } r = requests.get(url, params=params, timeout=10) d = r.json().get("data") if not d: return {} # f59 = 小数位数, 价格字段需除以 10^f59 还原真实值 dec = d.get("f59", 3) divisor = 10 ** dec def _p(key): v = d.get(key) if v is None or v == "-": return None return round(v / divisor, dec) return { "code": d.get("f57"), # 股票代码 "name": d.get("f58"), # 中文名 "price": _p("f43"), # 最新价 "high": _p("f44"), # 最高 "low": _p("f45"), # 最低 "open": _p("f46"), # 开盘 "volume": d.get("f47"), # 成交量(股) "amount": d.get("f48"), # 成交额 "turnover_rate": d.get("f55"), # 换手率(%) "prev_close": _p("f60"), # 昨收 "change_pct": round(d["f170"] / 100, 2) if d.get("f170") is not None else None, # 涨跌幅(%) } ``` --- ## Layer 2: K线层 ### 2.1 美股 K 线 — 新浪（主）+ Yahoo（备） 两个独立数据源。新浪最长可回溯到 1984 年；Yahoo 适合需要复权数据的场景。 > **注意：** 东财 push2his kline/get 端点实测不返回美股/港股数据（2026-05-20 验证），仅支持 A 股。美股/港股 K 线用新浪和 Yahoo。 ```python def us_stock_kline_sina(ticker: str, num: int = 120) -> list[dict]: """ 新浪美股日K — 可回溯到1984年 ticker: 如 "AAPL" 返回: [{date, open, high, low, close, volume}, ...] """ url = "https://stock.finance.sina.com.cn/usstock/api/jsonp.php/var/US_MinKService.getDailyK" params = {"symbol": ticker.upper(), "num": num} r = requests.get(url, params=params, headers={"Referer": "https://finance.sina.com.cn/"}, timeout=15) text = r.text # 解析 JSONP: var=([{...},...]) import json m = re.search(r'\((\[.+\])\)', text) if not m: return [] items = json.loads(m.group(1)) result = [] for item in items: result.append({ "date": item.get("d"), "open": float(item.get("o", 0)), "high": float(item.get("h", 0)), "low": float(item.get("l", 0)), "close": float(item.get("c", 0)), "volume": int(item.get("v", 0)), }) return result def stock_kline_yahoo(symbol: str, interval: str = "1d", range_: str = "6mo") -> list[dict]: """ Yahoo Finance chart API — 美股+港股通用，零crumb symbol: "AAPL" (美股) 或 "0700.HK" (港股) interval: "1d", "1wk", "1mo", "5m", "15m", "1h" range_: "1d", "5d", "1mo", "3mo", "6mo", "1y", "5y", "max" 返回: [{date, open, high, low, close, volume}, ...] """ url = f"https://query2.finance.yahoo.com/v8/finance/chart/{symbol}" params = {"interval": interval, "range": range_} r = requests.get(url, params=params, headers={ "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" }, timeout=15) r.raise_for_status() d = r.json() chart = d.get("chart", {}).get("result", [{}])[0] timestamps = chart.get("timestamp", []) quote = chart.get("indicators", {}).get("quote", [{}])[0] from datetime import datetime result = [] for i, ts in enumerate(timestamps): result.append({ "date": datetime.fromtimestamp(ts).strftime("%Y-%m-%d %H:%M") if "m" in interval or "h" in interval else datetime.fromtimestamp(ts).strftime("%Y-%m-%d"), "open": round(quote["open"][i], 2) if quote["open"][i] else 0, "high": round(quote["high"][i], 2) if quote["high"][i] else 0, "low": round(quote["low"][i], 2) if quote["low"][i] else 0, "close": round(quote["close"][i], 2) if quote["close"][i] else 0, "volume": int(quote["volume"][i]) if quote["volume"][i] else 0, }) return result ``` ### 2.2 港股 K 线 — Yahoo（唯一可用源） 港股 K 线只有 Yahoo 一个可用源（新浪港股K线已失效，东财 push2his 不返回港股K线数据）。 ```python # 港股 Yahoo K线: 直接调 stock_kline_yahoo("0700.HK") ``` --- ## Layer 3: 技术指标层 基于 K 线 OHLCV 数据的纯 Python 技术指标计算，零额外依赖。 **使用方式：** 先调 K 线函数获取数据，再传入技术指标函数： ```python klines = us_stock_kline_sina("AAPL", 120) macd = calc_macd(klines) rsi = calc_rsi(klines) ``` ### 3.1 移动平均线 MA / EMA ```python def _ema(values: list[float], period: int) -> list[float]: """EMA 指数移动平均（内部辅助）""" result = [values[0]] k = 2 / (period + 1) for v in values[1:]: result.append(v * k + result[-1] * (1 - k)) return result def calc_ma(klines: list[dict], periods: list[int] = None) -> list[dict]: """ 移动平均线 MA + EMA klines: K线数据 [{date, open, high, low, close, volume}, ...] periods: 周期列表，默认 [5, 10, 20, 60] 返回: [{date, close, ma5, ma10, ma20, ma60, ema12, ema26}, ...] """ if periods is None: periods = [5, 10, 20, 60] closes = [k["close"] for k in klines] # EMA 12/26（MACD 常用） ema12 = _ema(closes, 12) ema26 = _ema(closes, 26) result = [] for i, k in enumerate(klines): row = {"date": k["date"], "close": k["close"]} for p in periods: if i >= p - 1: row[f"ma{p}"] = round(sum(closes[i - p + 1:i + 1]) / p, 4) else: row[f"ma{p}"] = None row["ema12"] = round(ema12[i], 4) row["ema26"] = round(ema26[i], 4) result.append(row) return result ``` ### 3.2 MACD ```python def calc_macd(klines: list[dict], fast: int = 12, slow: int = 26, signal: int = 9) -> list[dict]: """ MACD (Moving Average Convergence Divergence) klines: K线数据 fast/slow/signal: 快线/慢线/信号线周期（默认 12/26/9） 返回: [{date, close, dif, dea, macd_hist}, ...] dif = EMA(fast) - EMA(slow) 金叉/死叉看 dif 穿越 dea dea = EMA(signal) of dif 信号线 macd_hist = (dif - dea) * 2 柱状图（红涨绿跌） """ closes = [k["close"] for k in klines] ema_fast = _ema(closes, fast) ema_slow = _ema(closes, slow) dif = [round(f - s, 4) for f, s in zip(ema_fast, ema_slow)] dea = _ema(dif, signal) result = [] for i, k in enumerate(klines): result.append({ "date": k["date"], "close": k["close"], "dif": round(dif[i], 4), "dea": round(dea[i], 4), "macd_hist": round((dif[i] - dea[i]) * 2, 4), }) return result ``` ### 3.3 RSI ```python def calc_rsi(klines: list[dict], periods: list[int] = None) -> list[dict]: """ RSI (Relative Strength Index) klines: K线数据 periods: 周期列表（默认 [6, 12, 24]） 返回: [{date, close, rsi6, rsi12, rsi24}, ...] RSI > 70 超买区（可能回调） RSI < 30 超卖区（可能反弹） """ if periods is None: periods = [6, 12, 24] closes = [k["close"] for k in klines] # 涨跌额序列 changes = [0.0] + [closes[i] - closes[i - 1] for i in range(1, len(closes))] gains = [max(c, 0) for c in changes] losses = [max(-c, 0) for c in changes] result = [] for i, k in enumerate(klines): row = {"date": k["date"], "close": k["close"]} for p in periods: if i < p: row[f"rsi{p}"] = None continue avg_gain = sum(gains[i - p + 1:i + 1]) / p avg_loss = sum(losses[i - p + 1:i + 1]) / p if avg_loss == 0: row[f"rsi{p}"] = 100.0 else: rs = avg_gain / avg_loss row[f"rsi{p}"] = round(100 - 100 / (1 + rs), 2) result.append(row) return result ``` ### 3.4 KDJ ```python def calc_kdj(klines: list[dict], n: int = 9, m1: int = 3, m2: int = 3) -> list[dict]: """ KDJ 随机指标 klines: K线数据 n: RSV 周期（默认9） m1/m2: K/D 平滑系数（默认3/3） 返回: [{date, close, k, d, j}, ...] K/D > 80 超买，K/D < 20 超卖 J > 100 或 J < 0 为极端信号 金叉: K 上穿 D；死叉: K 下穿 D """ k_val, d_val = 50.0, 50.0 result = [] for i, kline in enumerate(klines): if i < n - 1: result.append({"date": kline["date"], "close": kline["close"], "k": None, "d": None, "j": None}) continue window = klines[i - n + 1:i + 1] high_n = max(w["high"] for w in window) low_n = min(w["low"] for w in window) rsv = (kline["close"] - low_n) / (high_n - low_n) * 100 if high_n != low_n else 50.0 k_val = (1 / m1) * rsv + (1 - 1 / m1) * k_val d_val = (1 / m2) * k_val + (1 - 1 / m2) * d_val j_val = 3 * k_val - 2 * d_val result.append({ "date": kline["date"], "close": kline["close"], "k": round(k_val, 2), "d": round(d_val, 2), "j": round(j_val, 2), }) return result ``` ### 3.5 布林带 ```python def calc_boll(klines: list[dict], period: int = 20, num_std: float = 2.0) -> list[dict]: """ 布林带 (Bollinger Bands) klines: K线数据 period: 中轨 MA 周期（默认20） num_std: 标准差倍数（默认2） 返回: [{date, close, upper, middle, lower, bandwidth}, ...] 价格触及 upper → 可能超买 价格触及 lower → 可能超卖 bandwidth 收窄 → 即将变盘 """ closes = [k["close"] for k in klines] result = [] for i, k in enumerate(klines): if i < period - 1: result.append({"date": k["date"], "close": k["close"], "upper": None, "middle": None, "lower": None, "bandwidth": None}) continue window = closes[i - period + 1:i + 1] ma = sum(window) / period std = (sum((x - ma) ** 2 for x in window) / period) ** 0.5 upper = ma + num_std * std lower = ma - num_std * std result.append({ "date": k["date"], "close": k["close"], "upper": round(upper, 4), "middle": round(ma, 4), "lower": round(lower, 4), "bandwidth": round((upper - lower) / ma * 100, 2) if ma else None, }) return result ``` --- ## Layer 4: 基本面层 ### 4.1 财报三表 — 东财 datacenter 东财 datacenter 提供美股/港股的资产负债表、利润表、现金流量表，中文字段名，按科目行展开。 ```python def financial_statements_eastmoney(secucode: str, statement: str = "balance", page_size: int = 200) -> list[dict]: """ 东财 datacenter 财报三表 secucode: "AAPL.O" (NASDAQ) / "BABA.N" (NYSE) / "00700.HK" (港股) statement: "balance" / "income" / "cashflow" 返回: [{ITEM_NAME, AMOUNT, YOY_RATIO, REPORT, REPORT_DATE, ...}, ...] 注意: 数据按科目行展开，每行一个科目（如"流动资产合计"、"营业收入"等）， 同一期报告有多行。用 REPORT_DATE 分组可还原整张报表。 """ # 报表名映射（注意命名不统一：balance/income 用 F10，cashflow 用 SK） report_map = { "balance": {"us": "RPT_USF10_FN_BALANCE", "hk": "RPT_HKF10_FN_BALANCE"}, "income": {"us": "RPT_USF10_FN_INCOME", "hk": "RPT_HKF10_FN_INCOME"}, "cashflow": {"us": "RPT_USSK_FN_CASHFLOW", "hk": "RPT_HKSK_FN_CASHFLOW"}, } market = "hk" if secucode.endswith(".HK") else "us" report_name = report_map[statement][market] return eastmoney_datacenter( report_name=report_name, filter_str=f'(SECUCODE="{secucode}")', page_size=page_size, sort_columns="REPORT_DATE", sort_types="-1", ) # 每行字段: # SECUCODE, SECURITY_CODE, SECURITY_NAME_ABBR, REPORT_DATE, # STD_ITEM_CODE, ITEM_NAME (科目名), AMOUNT (金额), # YOY_RATIO (同比%), REPORT (如 "2026/Q2"), REPORT_TYPE, # ACCOUNT_STANDARD (如 "美国会计准则"/"国际会计准则"), # CURRENCY (如 "美元"/"人民币") ``` ### 4.2 关键财务指标(中文) — 东财 GMAININDICATOR 东财 datacenter 的 GMAININDICATOR 报表，提供中文关键财务指标概览。美股 49 字段、港股 75 字段，包含 ROE/ROA/EPS/毛利率/资产负债率/流动比率等，按季度报告。 ```python def key_indicators_eastmoney(secucode: str, page_size: int = 4) -> list[dict]: """ 东财 GMAININDICATOR 关键财务指标（中文） secucode: "AAPL.O" (NASDAQ) / "BABA.N" (NYSE) / "00700.HK" (港股) page_size: 返回最近几期报告（默认4期=一年） 返回: [{REPORT_DATE, OPERATE_INCOME, BASIC_EPS, ROE_AVG, ROA, ...}, ...] 美股核心字段(49): OPERATE_INCOME(营收), GROSS_PROFIT(毛利), GROSS_PROFIT_RATIO(毛利率%), PARENT_HOLDER_NETPROFIT(归母净利), NET_PROFIT_RATIO(净利率%), BASIC_EPS, DILUTED_EPS, ROE_AVG(平均ROE%), ROA(%), CURRENT_RATIO(流动比率), DEBT_ASSET_RATIO(资产负债率%), OPERATE_INCOME_YOY(营收同比%), BASIC_EPS_YOY(EPS同比%) 港股额外字段(75): BPS(每股净资产), ROIC(投入资本回报率), EQUITY_RATIO(产权比率), HOLDER_PROFIT(股东应占溢利), OCF_SALES(经营现金流/营收%), DPS_HKD(每股股息), DIVI_RATIO(股息率%), PER_NETCASH_OPERATE(每股经营现金流) """ market = "hk" if secucode.endswith(".HK") else "us" report_name = f"RPT_{'HK' if market == 'hk' else 'US'}F10_FN_GMAININDICATOR" return eastmoney_datacenter( report_name=report_name, filter_str=f'(SECUCODE="{secucode}")', page_size=page_size, sort_columns="REPORT_DATE", sort_types="-1", ) ``` ### 4.3 关键财务指标(英文) — Yahoo quoteSummary Yahoo quoteSummary 的 `financialData` + `defaultKeyStatistics` 模块提供最核心的估值指标。 ```python def key_statistics(symbol: str) -> dict: """ Yahoo 关键财务指标 symbol: "AAPL" (美股) 或 "0700.HK" (港股) 返回: PE/PB/EV/EBITDA/利润率/目标价/ROE/Beta 等 """ data = yahoo_quote_summary(symbol, ["financialData", "defaultKeyStatistics", "summaryDetail"]) fd = data.get("financialData", {}) ks = data.get("defaultKeyStatistics", {}) sd = data.get("summaryDetail", {}) def _val(d, key): v = d.get(key, {}) return v.get("raw") if isinstance(v, dict) else v return { # 价格相关 "current_price": _val(fd, "currentPrice"), "target_high": _val(fd, "targetHighPrice"), "target_low": _val(fd, "targetLowPrice"), "target_mean": _val(fd, "targetMeanPrice"), "recommendation": fd.get("recommendationKey"), # buy/hold/sell # 估值指标 "trailing_pe": _val(sd, "trailingPE"), "forward_pe": _val(ks, "forwardPE"), "peg_ratio": _val(ks, "pegRatio"), "price_to_book": _val(ks, "priceToBook"), "enterprise_value": _val(ks, "enterpriseValue"), "ev_to_ebitda": _val(ks, "enterpriseToEbitda"), "ev_to_revenue": _val(ks, "enterpriseToRevenue"), # 盈利能力 "profit_margin": _val(ks, "profitMargins"), "operating_margin": _val(fd, "operatingMargins"), "gross_margin": _val(fd, "grossMargins"), "return_on_equity": _val(fd, "returnOnEquity"), "return_on_assets": _val(fd, "returnOnAssets"), # 成长性 "earnings_growth": _val(fd, "earningsGrowth"), "revenue_growth": _val(fd, "revenueGrowth"), # 风险 "beta": _val(ks, "beta"), "short_ratio": _val(ks, "shortRatio"), # 股息 "dividend_yield": _val(sd, "dividendYield"), "payout_ratio": _val(ks, "payoutRatio"), # 规模 "market_cap": _val(sd, "marketCap"), "total_revenue": _val(fd, "totalRevenue"), "total_cash": _val(fd, "totalCash"), "total_debt": _val(fd, "totalDebt"), } ``` ### 4.4 分析师预期与评级 — Yahoo quoteSummary ```python def analyst_estimates(symbol: str) -> dict: """ Yahoo 分析师预期 — EPS预测/评级趋势/升降级历史 symbol: "AAPL" 或 "0700.HK" """ data = yahoo_quote_summary(symbol, [ "earningsTrend", "recommendationTrend", "upgradeDowngradeHistory", "earnings", "earningsHistory", ]) # EPS 趋势 et = data.get("earningsTrend", {}).get("trend", []) eps_trend = [] for t in et: eps_trend.append({ "period": t.get("period"), "end_date": t.get("endDate"), "eps_estimate": t.get("earningsEstimate", {}).get("avg", {}).get("raw"), "eps_high": t.get("earningsEstimate", {}).get("high", {}).get("raw"), "eps_low": t.get("earningsEstimate", {}).get("low", {}).get("raw"), "revenue_estimate": t.get("revenueEstimate", {}).get("avg", {}).get("raw"), "num_analysts": t.get("earningsEstimate", {}).get("numberOfAnalysts", {}).get("raw"), }) # 评级趋势 (最近4个月) rt = data.get("recommendationTrend", {}).get("trend", []) rating_trend = [] for r_ in rt: rating_trend.append({ "period": r_.get("period"), "strong_buy": r_.get("strongBuy"), "buy": r_.get("buy"), "hold": r_.get("hold"), "sell": r_.get("sell"), "strong_sell": r_.get("strongSell"), }) # 升降级历史 (最近20条) udh = data.get("upgradeDowngradeHistory", {}).get("history", [])[:20] upgrades = [] for u in udh: upgrades.append({ "date": u.get("epochGradeDate"), "firm": u.get("firm"), "to_grade": u.get("toGrade"), "from_grade": u.get("fromGrade"), "action": u.get("action"), # up/down/main/init }) return { "eps_trend": eps_trend, "rating_trend": rating_trend, "upgrade_downgrade": upgrades, } ``` ### 4.5 机构持仓 — Yahoo quoteSummary ```python def institutional_holders(symbol: str) -> dict: """ Yahoo 机构持仓 — 前10大机构 + 内部人持股比例 symbol: "AAPL" 或 "0700.HK" """ data = yahoo_quote_summary(symbol, ["institutionOwnership", "majorHoldersBreakdown"]) # 持股比例总览 mhb = data.get("majorHoldersBreakdown", {}) def _val(d, key): v = d.get(key, {}) return v.get("raw") if isinstance(v, dict) else v overview = { "insiders_pct": _val(mhb, "insidersPercentHeld"), "institutions_pct": _val(mhb, "institutionsPercentHeld"), "institutions_float_pct": _val(mhb, "institutionsFloatPercentHeld"), "institutions_count": _val(mhb, "institutionsCount"), } # 前10大机构 io = data.get("institutionOwnership", {}).get("ownershipList", []) top_holders = [] for h in io[:10]: top_holders.append({ "name": h.get("organization"), "shares": _val(h, "position"), "value": _val(h, "value"), "pct_held": _val(h, "pctHeld"), "report_date": h.get("reportDate", {}).get("fmt") if isinstance(h.get("reportDate"), dict) else None, }) return {"overview": overview, "top_holders": top_holders} ``` ### 4.6 年度/季度财报明细 — Yahoo quoteSummary 东财 datacenter 按科目行展开，Yahoo 直接返回完整报表结构，两个互补。 ```python def financial_statements_yahoo(symbol: str, quarterly: bool = False) -> dict: """ Yahoo 财报三表 — 结构化完整报表 symbol: "AAPL" 或 "0700.HK" quarterly: False=年度, True=季度 返回: {"income": [...], "balance": [...], "cashflow": [...]} """ suffix = "Quarterly" if quarterly else "" data = yahoo_quote_summary(symbol, [ f"incomeStatementHistory{suffix}", f"balanceSheetHistory{suffix}", f"cashflowStatementHistory{suffix}", ]) def _extract(statements): result = [] …(truncated)