Files

T

tomatocream b5bf689e72 docs: add API references, mapping corrections, and verification script

- Add yfinance.org and defeatbeta-api.org reference docs
- Fix defeatbeta_mapping.org: deprecated yfinance property names
  (quarterly_financials→quarterly_income_stmt, financials→income_stmt),
  longName vs longBusinessSummary conceptual mismatch, cashflow note typo
- Add Mapping Limitations section with live verification results (AAPL):
  DuckDB 1.4.3 incompatibility, format differences, coverage gaps
- Add docs/test_mapping.py as runnable mapping verification script
- Add offline.py, persistent_cache.py, download_data.py, warmup_cache.py
  for offline/cached defeatbeta usage
- Add aapl_yfinance.py exploration script and quant.py scaffold
- Add .envrc (uv layout) and update pyproject.toml + uv.lock

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-04-26 15:33:21 +08:00

12 KiB

Raw Permalink Blame History

yfinance API Reference

Overview
- Installation
- Quick Start
Top-Level Functions
Config
Ticker(symbol)
Tickers('SYM1 SYM2 …')
Market(market_code)
Calendars
Search(query)
Lookup(query)
WebSocket(symbols, …)
AsyncWebSocket(symbols, …)
Sector(sector_key)
Industry(industry_key)
Query Builders (Screener)
download() Parameters
Advanced Features
Legal Disclaimer

Overview

yfinance offers a Pythonic way to fetch financial & market data from Yahoo! Finance.

Installation

pip install yfinance

Quick Start

import yfinance as yf

# Single ticker
dat = yf.Ticker("MSFT")
dat.info
dat.history(period='1mo')
dat.option_chain(dat.options[0]).calls

# Multiple tickers
tickers = yf.Tickers('MSFT AAPL GOOG')
tickers.tickers['MSFT'].info
yf.download(['MSFT', 'AAPL', 'GOOG'], period='1mo')

# Funds
spy = yf.Ticker('SPY').funds_data
spy.description
spy.top_holdings

Top-Level Functions

Function	Description
`yf.download(tickers, ...)`	Download market data for multiple tickers
`yf.enable_debug_mode()`	Enable verbose debug logging
`yf.set_tz_cache_location(path)`	Set timezone cache directory
`yf.screen(query)`	Run equity/fund/ETF screener queries

Config

Setting	Description
`yf.config.debug.logging = True`	Enable debug logging
`yf.config.user_agent = 'custom'`	Custom user agent

Ticker(symbol)

Price History

Property/Method	Returns
`.history(period, start, end, interval, ...)`	OHLCV DataFrame
`.get_history_metadata()`	Dict with currency, exchange, etc.
`.get_dividends()`	Dividend history (Series)
`.dividends`	Cached dividend history
`.get_splits()`	Stock split history (Series)
`.splits`	Cached split history
`.get_actions()`	Dividends + splits combined (Series)
`.actions`	Cached actions history
`.get_capital_gains()`	Capital gains distributions (Series)
`.capital_gains`	Cached capital gains
`.get_shares_full()`	Full shares outstanding history

Info & News

Property/Method	Returns
`.get_info()` / `.info`	Full company info dict
`.get_fast_info()` / `.fast_info`	Quick-access key metrics
`.get_news()` / `.news`	Recent news articles (DataFrame)
`.isin`	ISIN identifier
`.get_isin()`	ISIN as string

Financial Statements

Property/Method	Returns
`.income_stmt`	Annual income statement
`.quarterly_income_stmt`	Quarterly income statement
`.ttm_income_stmt`	Trailing-twelve-months income statement
`.balance_sheet`	Annual balance sheet
`.cashflow`	Annual cash flow statement
`.quarterly_cashflow`	Quarterly cash flow
`.ttm_cashflow`	TTM cash flow
`.get_income_stmt()`	Alias for income_stmt
`.get_balance_sheet()`	Alias for balance_sheet
`.get_cashflow()`	Alias for cashflow

Earnings & Calendar

Property/Method	Returns
`.earnings`	Annual earnings summary
`.calendar`	Upcoming earnings/dividends dates
`.get_earnings_dates()`	Historical & upcoming earnings dates
`.earnings_dates`	Cached earnings dates
`.get_sec_filings()`	SEC filing history
`.sec_filings`	Cached SEC filings

Analysis & Estimates

Property/Method	Returns
`.get_recommendations()`	Historical analyst recommendations
`.recommendations`	Cached recommendations
`.get_recommendations_summary()`	Summary of buy/hold/sell
`.recommendations_summary`	Cached summary
`.get_upgrades_downgrades()`	Analyst upgrades/downgrades
`.upgrades_downgrades`	Cached upgrades/downgrades
`.get_sustainability()`	ESG scores
`.sustainability`	Cached ESG
`.get_analyst_price_targets()`	Price target estimates
`.analyst_price_targets`	Cached price targets
`.get_earnings_estimate()`	Earnings estimates
`.earnings_estimate`	Cached earnings estimates
`.get_revenue_estimate()`	Revenue estimates
`.revenue_estimate`	Cached revenue estimates
`.get_earnings_history()`	Earnings surprise history
`.earnings_history`	Cached earnings history
`.get_eps_trend()`	EPS trend revisions
`.eps_trend`	Cached EPS trend
`.get_eps_revisions()`	EPS revision counts
`.eps_revisions`	Cached EPS revisions
`.get_growth_estimates()`	Growth rate estimates
`.growth_estimates`	Cached growth estimates

Holdings & Insider Activity

Property/Method	Returns
`.get_funds_data()` / `.funds_data`	Fund info (for ETFs/mutual funds)
`.get_insider_purchases()` / `.insider_purchases`	Insider purchase records
`.get_insider_transactions()` / `.insider_transactions`	Insider trade history
`.get_insider_roster_holders()` / `.insider_roster_holders`	Insider roster
`.get_major_holders()` / `.major_holders`	Ownership breakdown
`.get_institutional_holders()` / `.institutional_holders`	Institutional holders
`.get_mutualfund_holders()` / `.mutualfund_holders`	Mutual fund holders

Options

Method	Returns
`.options`	Tuple of available expiration dates
`.option_chain(date)`	Calls & puts DataFrame for a date

Tickers('SYM1 SYM2 …')

Multiple tickers class.

Property	Returns
`.tickers['SYM'].info`	Access individual Ticker objects
`.tickers['SYM'].history()`	Get history per ticker

Market(market_code)

Market summary class.

Method/Property	Returns
`.status`	Market open/closed status
`.summary()`	Market summary data

Calendars

Calendar events class.

Method	Returns
`.earnings()`	Earnings calendar
`.dividends()`	Dividend calendar
`.splits()`	Splits calendar
`.ipo()`	IPO calendar

Search(query)

Search class for quotes and news.

Property/Method	Returns
`.quotes`	Search result quotes
`.news`	Search result news
`.lists`	Watchlists/lists
`.nav`	Navigation results
`.research`	Research reports
`.get_quotes()`	Fetch quotes
`.get_news()`	Fetch news

Lookup(query)

Ticker lookup class.

Method	Returns
`.get_quotes()`	Lookup matching quotes

WebSocket(symbols, …)

Live streaming data (synchronous).

Method	Description
`.connect()`	Open WebSocket connection
`.subscribe(symbols)`	Subscribe to symbols
`.unsubscribe(symbols)`	Unsubscribe from symbols
`.close()`	Close connection

AsyncWebSocket(symbols, …)

Live streaming data (asynchronous).

Same methods as WebSocket, but async.

Sector(sector_key)

Sector information class.

Property/Method	Returns
`.key`	Sector identifier
`.name`	Sector name
`.symbol`	Associated ETF symbol
`.top_etfs`	Top ETFs in sector
`.top_companies`	Top companies in sector
`.industries`	Industries within sector

Industry(industry_key)

Industry information class.

Property/Method	Returns
`.key`	Industry identifier
`.name`	Industry name
`.sector_key`	Parent sector
`.top_companies`	Top companies in industry

Query Builders (Screener)

Class	Description
`EquityQuery`	Build equity filter queries
`FundQuery`	Build mutual fund filter queries
`ETFQuery`	Build ETF filter queries
`yf.screen(query)`	Execute a query and return results

download() Parameters

yf.download(
    tickers,           # str or list of tickers
    period="1mo",      # 1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max
    start=None,        # datetime or str "YYYY-MM-DD"
    end=None,
    interval="1d",     # 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo
    group_by="column", # "column" or "ticker"
    auto_adjust=False,
    back_adjust=False,
    repair=False,      # Enable price repair
    keepna=False,
    proxy=None,
    timeout=10,
    threads=True,
    progress=True,
)

Advanced Features

Logging

Enable debug logging:

yf.config.debug.logging = True

Caching

Persistent cache is enabled by default
Set custom cache location: yf.set_tz_cache_location(path)

Price Repair

Enable with repair=True in download() or history()
Fixes NaN values, bad splits, and dividend adjustments
Dividend repair also available

Multi-Level Column Index

When downloading multiple tickers, columns are MultiIndex
group_by="column" or group_by="ticker"

Legal Disclaimer

Yahoo!, Y!Finance, and Yahoo! finance are registered trademarks of Yahoo, Inc.

yfinance is not affiliated, endorsed, or vetted by Yahoo, Inc. It's an open-source tool that uses Yahoo's publicly available APIs, and is intended for research and educational purposes.

You should refer to Yahoo!'s terms of use for details on your rights to use the actual data downloaded. The Yahoo! finance API is intended for personal use only.

12 KiB Raw Permalink Blame History