yahooquery 技能

通过 yahooquery Python 库全面访问 Yahoo Finance 数据。该库提供对几乎所有 Yahoo Finance 接口的编程式访问能力，涵盖实时行情、基本面数据、分析师预测、期权信息、新闻以及高级研究报告。

核心类

1. Ticker（公司特定数据）

用于检索一个或多个证券数据的主要接口。

from yahooquery import Ticker

# 单个或多个股票代码
aapl = Ticker('AAPL')
tickers = Ticker('AAPL MSFT NVDA', asynchronous=True)

2. Screener（预定义股票列表）

访问按筛选条件预构建的股票筛选器，用于发现符合特定标准的股票。

from yahooquery import Screener

s = Screener()
screeners = s.available_screeners  # 列出所有可用的筛选器
data = s.get_screeners(['day_gainers', 'most_actives'], count=10)

3. Research（需 Premium 订阅）

访问专有研究报告与交易策略建议。

from yahooquery import Research

r = Research(username='you@email.com', password='password')
reports = r.reports(report_type='Analyst Report', report_date='Last Week')
trades = r.trades(trend='Bullish', term='Short term')

Ticker 类：数据模块

Ticker 类通过属性和方法暴露数十个数据端点。

📊 财务报表

• .income_statement(frequency='a', trailing=True) — 损益表（年度/季度）
• .balance_sheet(frequency='a', trailing=True) — 资产负债表
• .cash_flow(frequency='a', trailing=True) — 现金流量表
• .all_financial_data(frequency='a') — 合并财务数据 + 估值指标
• .valuation_measures — 不同期间的 EV/EBITDA、P/E、P/B、P/S 等估值比率

📈 行情与市场数据

• .price — 当前价格、市值、52 周区间
• .history(period='1y', interval='1d', start=None, end=None) — 历史 OHLC 数据
  • period：可选值包括 1d、5d、1mo、3mo、6mo、1y、2y、5y、10y、ytd、max
  • interval：可选值包括 1m、2m、5m、15m、30m、60m、90m、1h、1d、5d、1wk、1mo、3mo
• .option_chain — 完整期权链（涵盖所有到期日）

🔍 分析与预测

• .calendar_events — 下一财报发布日期、EPS/营收预测
• .earning_history — 过去四个季度的实际 EPS 与预测 EPS 对比
• .earnings — 历史季度/年度盈利与营收数据
• .earnings_trend — 分析师对未来各期的盈利预测趋势
• .recommendation_trend — 买入/卖出/持有评级的历史变动
• .gradings — 近期分析师上调/下调评级记录

🏢 公司基本面

• .asset_profile — 公司地址、所属行业与板块、业务摘要、高管信息
• .company_officers — 高管名单及其薪酬详情
• .summary_profile — 公司概况精简版
• .key_stats — 市盈率（前瞻）、利润率、Beta 值、流通股数等关键统计指标
• .financial_data — 财务 KPI（如 ROE、ROA、资产负债率、各项利润率）

👥 所有权与公司治理

• .insider_holders — 内部人持股者列表及持股情况
• .insider_transactions — 内部人近期买卖交易记录
• .institution_ownership — 顶级机构投资者持仓
• .fund_ownership — 顶级共同基金持仓
• .major_holders — 所有权概览（机构持股比例、内部人持股比例、流通股比例）

🌍 ESG 与评级

• .esg_scores — 环境（E）、社会（S）、治理（G）评分及争议事件
• .recommendation_rating — 分析师共识评级（Strong Buy → Strong Sell）

📰 新闻与洞察

• .news() — 最近发布的新闻文章
• .technical_insights — 看涨/看跌技术形态分析

💰 仅适用于基金与 ETF

• .fund_holding_info — 前十大持仓、债券/股票资产分布
• .fund_performance — 历史业绩与回报表现
• .fund_bond_holdings / .fund_bond_ratings — 债券久期与信用评级
• .fund_equity_holdings — 股票持仓的 P/E、P/B、P/S 指标

📊 其他模块

• .summary_detail — 交易统计（当日最高/最低价、成交量、平均成交量）
• .default_key_statistics — 企业价值、滚动市盈率（Trailing P/E）、前瞻市盈率（Forward P/E）
• .index_trend — 相对于基准指数的表现
• .quote_type — 证券类型、交易所、市场

全局函数

import yahooquery as yq

# 搜索
results = yq.search('NVIDIA')

# 市场数据
market = yq.get_market_summary(country='US')  # 主要股指快照
trending = yq.get_trending(country='US')  # 热门股票

# 工具函数
currencies = yq.get_currencies()  # 支持的货币列表
exchanges = yq.get_exchanges()  # 交易所列表
rate = yq.currency_converter('USD', 'EUR')  # 汇率查询

配置项与关键字参数

Ticker、Screener 和 Research 类均支持以下可选参数：

性能与可靠性

• asynchronous=True — 异步发起请求（适用于多个股票代码）
• max_workers=8 — 并发请求数量（仅在启用异步时生效）
• retry=5 — 请求失败后的重试次数
• backoff_factor=0.3 — 重试之间的指数退避因子
• status_forcelist=[429, 500, 502, 503, 504] — 触发重试的 HTTP 状态码列表
• timeout=5 — 单次请求超时时间（秒）

数据格式与校验

• formatted=False — 若设为 True，返回的数据结构包含 {raw, fmt, longFmt} 字段
• validate=True — 实例化时校验股票代码有效性（无效代码将存入 .invalid_symbols）
• country='United States' — 地区化数据/新闻（支持 france、germany、canada 等）

网络与认证

• proxies={'http': 'http://proxy:port'} — HTTP/HTTPS 代理配置
• user_agent='...' — 自定义 User-Agent 字符串
• verify=True — 启用 SSL 证书验证
• username='you@email.com' / password='...' — Yahoo Finance Premium 登录凭据

高级选项（共享会话）

• session=... / crumb=... — 在 Research 与 Ticker 实例之间共享认证上下文

最佳实践

1. 多股票代码使用异步模式

tickers = Ticker('AAPL MSFT NVDA TSLA', asynchronous=True)
prices = tickers.price  # 返回以股票代码为键的字典

2. 处理 DataFrame

大多数财务相关方法返回 pandas.DataFrame。如需 JSON 输出，请进行转换：

df = aapl.income_statement()
print(df.to_json(orient='records', date_format='iso'))

3. 历史数据 — 1 分钟级间隔

Yahoo 限制单次请求最多获取 7 天的 1 分钟级数据。若需获取 30 天数据：

tickers = Ticker('AAPL', asynchronous=True)
df = tickers.history(period='1mo', interval='1m')  # 自动拆分为 4 次请求

4. Premium 用户：Research 与 Ticker 结合使用

r = Research(username='...', password='...')
reports = r.reports(sector='Technology', investment_rating='Bullish')

# 复用 Research 的会话对象初始化 Ticker
tickers = Ticker('AAPL', session=r.session, crumb=r.crumb)
data = tickers.asset_profile

常见使用场景

投资组合分析

portfolio = Ticker('AAPL MSFT NVDA', asynchronous=True)
summary = portfolio.summary_detail
earnings = portfolio.earnings
history = portfolio.history(period='1y')

股票筛选与发现

s = Screener()
gainers = s.get_screeners(['day_gainers'], count=20)
# 返回包含价格、成交量、涨跌幅等字段的 DataFrame

期权分析

nvda = Ticker('NVDA')
options = nvda.option_chain
# 可按认购/认沽、行权价、到期日等条件筛选

财报日历

tickers = Ticker('AAPL MSFT NVDA')
calendar = tickers.calendar_events
# 显示下一财报发布日期及分析师预测

参考文档

完整 API 文档位于：/Users/henryzha/.openclaw/workspace-research/skills/yahooquery/references/

• index.md — 类与函数总览
• ticker/ — Ticker 类所有方法的详细说明
• screener.md — Screener 类使用指南
• research.md — Research 类（Premium 功能）
• keyword_arguments.md — 所有配置选项完整列表
• misc.md — 全局工具函数说明
• advanced.md — Research 与 Ticker 间共享会话的高级用法

运行环境

• 安装方式：python3 -m pip install yahooquery
• 依赖项：pandas、requests-futures、tqdm、beautifulsoup4、lxml
• Python 版本要求：3.7+

注意事项

• Yahoo Finance 可能对请求进行频率限制或封禁。建议合理使用 retry、backoff_factor 和 status_forcelist 提升容错能力。
• 高级功能（Research 类）需订阅付费版 Yahoo Finance Premium。
• 数据准确性与时效性取决于 Yahoo Finance 所依赖的上游数据提供商。