yahoo-finance

Yahoo Finance — 直接 API（不使用 yfinance）

Yahoo Finance 非官方 API。通过直接 HTTP requests获取股票、ETF、加密货币、外汇、债券、指数、期权、基本面和新闻数据，不使用 yfinance 或任何封装库。

基础 URL： https://query1.finance.yahoo.com 备用地址： https://query2.finance.yahoo.com

---

⚠️ 重要提示

• Yahoo 自 2017 年起没有官方公共 API。这些端点均为非官方端点，可能会在不另行通知的情况下发生变化。
• 某些端点需要通过cookie + crumb进行身份验证（下文会说明）。
• v8/finance/chart 端点无需身份验证（只需使用浏览器的 User-Agent）。
• 始终实现速率限制和错误处理。

---

完整文档

如需查阅所有端点、字段、JSON 结构、错误代码、国际股票代码、速率限制策略和详细示例，请参阅：

📖 references/API_REFERENCE.md

该文档包括：

• quoteSummary 的 33 个模块及每个字段的说明
• 每个端点的完整 JSON 响应
• 国际股票代码（阿根廷为 .BA，巴西为 .SA 等）
• WebSocket 流式传输
• 筛选器、查询、热门趋势
• 使用指数退避和 User-Agent 轮换的速率限制策略

---

身份验证：Cookie + Crumb

多个端点需要 crumb（CSRF 令牌），通过会话 cookie 获取。

import requests

BASE = "https://query1.finance.yahoo.com"
HEADERS = {
    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
}

def yahoo_session():
    """Retorna requests.Session con cookie A3 y crumb."""
    s = requests.Session()
    s.headers.update(HEADERS)
    s.get("https://fc.yahoo.com", timeout=10)
    crumb = s.get(f"{BASE}/v1/test/getcrumb", timeout=10).text.strip()
    s.params = {"crumb": crumb}
    return s

# Uso:
# s = yahoo_session()
# r = s.get("https://query1.finance.yahoo.com/v7/finance/quote?symbols=AAPL,MSFT")

按身份验证要求划分的端点

无需身份验证（仅需 User-Agent）	需要 crumb
v8/finance/chart（历史数据）	v7/finance/quote（价格）
v1/finance/search（搜索）	v10/finance/quoteSummary（基本面）
v1/finance/trending（趋势）	v7/finance/options（期权）
v1/finance/lookup（查询）	v6/finance/recommendationsbysymbol

---

端点 — 快速概览

1. OHLCV 历史数据 — v8/finance/chart

GET https://query1.finance.yahoo.com/v8/finance/chart/{symbol}?range=1y&interval=1d

参数	示例
range	1d、5d、1mo、3mo、6mo、1y、5y、10y、ytd、max
interval	1m、5m、15m、1h、1d、1wk、1mo
events	div,splits（包括股息和拆股）

import requests
headers = {"User-Agent": "Mozilla/5.0 (...) Chrome/120.0.0.0 Safari/537.36"}
r = requests.get("https://query1.finance.yahoo.com/v8/finance/chart/AAPL",
                 params={"range": "1y", "interval": "1d", "events": "div,splits"},
                 headers=headers)
data = r.json()["chart"]["result"][0]
# data["timestamp"] -> fechas Unix
# data["indicators"]["quote"][0] -> open, high, low, close, volume
# data["indicators"]["adjclose"][0] -> precios ajustados
# data["events"] -> dividendos y splits

2. 报价 — v7/finance/quote

s = yahoo_session()
r = s.get("https://query1.finance.yahoo.com/v7/finance/quote?symbols=AAPL,MSFT,GOOGL")
quotes = r.json()["quoteResponse"]["result"]
for q in quotes:
    print(q["symbol"], q["regularMarketPrice"], q["regularMarketChangePercent"])

字段：regularMarketPrice、regularMarketChangePercent、marketCap、trailingPE、fiftyTwoWeekHigh/Low、dividendYield、volume、marketState（盘前/常规交易时段/盘后/休市）。

3. 基本面 — v10/finance/quoteSummary

s = yahoo_session()
r = s.get("https://query1.finance.yahoo.com/v10/finance/quoteSummary/AAPL",
          params={"modules": "assetProfile,financialData,defaultKeyStatistics,incomeStatementHistory,balanceSheetHistory,cashflowStatementHistory,earnings,recommendationTrend"})
fundamentals = r.json()["quoteSummary"]["result"][0]
profile = fundamentals["assetProfile"]           # sector, industry, employees, description
financials = fundamentals["financialData"]        # EBITDA, revenue, margins, ROE, ROA
stats = fundamentals["defaultKeyStatistics"]      # beta, shares, PE, PEG, short info

共有 33 个可用模块。完整列表请参阅 API_REFERENCE.md 第 4 节。

4. 期权 — v7/finance/options

s = yahoo_session()
r = s.get("https://query1.finance.yahoo.com/v7/finance/options/AAPL")
data = r.json()["optionChain"]["result"][0]
expirations = data["expirationDates"]
strikes = data["strikes"]
options = data["options"][0]  # calls + puts

5. 搜索 + 新闻 — v1/finance/search

r = requests.get("https://query1.finance.yahoo.com/v1/finance/search",
                 params={"q": "Apple", "quotesCount": 3, "newsCount": 5},
                 headers=HEADERS)
data = r.json()
# data["quotes"] -> tickers encontrados
# data["news"] -> noticias relacionadas

---

脚本

脚本	描述
batch_fetch.py	多股票代码批量获取，使用令牌桶 + ThreadPoolExecutor。报价批处理（所有代码通过 1 个请求获取）。并行获取图表数据，同时遵守速率限制。
fetch_all.py	综合脚本：获取历史数据 + 报价 + 基本面 + 期权 + 搜索 + 推荐。适用于任何股票代码，可通过 CLI 参数配置。
fetch_quote.py	快速获取指定股票代码的报价 + 基本面。
download_historical.py	将 OHLCV 历史数据下载为 CSV。

batch_fetch.py — 具有速率限制的多代码批量获取

# Test seguro (3 tickers, solo chart, 2 req/s)
py scripts/batch_fetch.py --tickers AAPL,MSFT,NVDA --chart --rate 2.0

# Batch completo (quote en 1 request + charts en paralelo)
py scripts/batch_fetch.py --tickers AAPL,MSFT,NVDA,GOOGL,META,AMZN,TSLA --all --rate 2.0 --workers 4

# Solo quotes (siempre 1 request, imposible rate-limit)
py scripts/batch_fetch.py --tickers AAPL,MSFT,NVDA,GOOGL --quote

# Personalizar rate + workers
py scripts/batch_fetch.py --tickers AAPL,MSFT,NVDA --all --rate 1.5 --workers 3 --range 5y

主要标志：

• --rate：令牌桶的令牌数/秒（默认值：2.0 — 安全上限）
• --burst：突发时可累积的令牌数（默认值：5）
• --workers：并行线程数（默认值：4）

架构：

1. 阶段 1 — 批量报价：所有代码通过 1 个请求获取（v7/finance/quote?symbols=AAPL,MSFT,...）
2. 阶段 2 — 令牌桶：使用 ThreadPoolExecutor，由多个 worker 共享线程安全的 TokenBucket。每个 worker 在每次请求前获取一个令牌。速率为 2 req/s、burst=5 时，最多可以立即发起 5 个请求而不阻塞；之后令牌桶会稳定吞吐量。

fetch_all.py — 主脚本

python scripts/fetch_all.py --ticker AAPL --all                     # Todo lo disponible
python scripts/fetch_all.py --ticker GGAL --all --range 5y --interval 1d  # GGAL con 5 años
python scripts/fetch_all.py --ticker MSFT --chart --range max        # Histórico completo
python scripts/fetch_all.py --ticker NVDA --quote --fundamentals     # Quote + fundamentals
python scripts/fetch_all.py --ticker TSLA --all --all-modules        # Todos los módulos (~33)
python scripts/fetch_all.py --ticker AAPL --options                  # Solo opciones
python scripts/fetch_all.py -t AAPL -o mi_data.json -q               # Output a archivo, quiet

主要标志：

• --all：获取所有数据（图表、报价、基本面、期权、搜索、推荐）
• --chart：OHLCV 历史数据
• --quote：实时价格
• --fundamentals：基本面数据（quoteSummary）
• --options：期权链
• --search：搜索和新闻
• --range / --interval：控制历史数据
• --modules / --all-modules：quoteSummary 模块
• --output：JSON 输出文件

GGAL 实际测试（已测试）

>> Chart (1y, 1d)... OK 250 bars
>> Quote...             OK Price: $50.33 (-1.62%)
>> Fundamentals...      OK 12 módulos (core)
>> Options...           OK 5 expiration dates, 17 calls, 19 puts
>> Search+News...       OK 5 news items
Guardado en: ggal_temp.json  (123 KB)

---

国际股票代码

Yahoo Finance 使用后缀表示美国以外的市场：

市场	后缀	示例
阿根廷（BCBA）	.BA	GGAL.BA、YPFD.BA
巴西（Bovespa）	.SA	PETR4.SA、VALE3.SA
墨西哥（BMV）	.MX	WALMEX.MX
加密货币	-USD	BTC-USD、ETH-USD
外汇	=X	EURUSD=X
指数	^	^GSPC（S&P 500）

完整列表请参见 API_REFERENCE.md 第 14 节。

---

速率限制

限制	行为
~2 req/s	安全
3-5 req/s	触发 429 的概率较高
>10 req/s	IP 临时封禁

始终在请求之间使用 time.sleep(0.5)，并实现指数退避。

批量获取多个代码时，请使用 batch_fetch.py，该脚本通过令牌桶实现 2 req/s、burst 为 5 的速率限制。与 yfinance（没有速率限制器，会同时启动 N 个线程）不同，batch_fetch 可确保总体吞吐量不会超过安全上限。

---

常见错误

错误	原因	解决方案
401 Unauthorized	缺少 crumb	使用 yahoo_session()
429 Too Many Requests	速率限制	等待 30-60s
Bad Request	crumb 已过期	重新生成 crumb
result 为空	代码无效	先通过 search 验证
Python-requests 被拦截	默认 User-Agent	设置为浏览器的 User-Agent

---

skill 结构

skills/yahoo-finance/
├── SKILL.md                          # Este archivo (quickstart)
├── references/
│   └── API_REFERENCE.md              # Documentación completa de todos los endpoints
└── scripts/
    ├── batch_fetch.py                # Batch multi-ticker con rate limiting (recomendado)
    ├── fetch_all.py                  # Script integral
    ├── fetch_quote.py                # Quote + fundamentals rápido
    └── download_historical.py        # Históricos a CSV