#+title: yfinance API Reference #+subtitle: Version 1.3.0 #+author: Ran Aroussi #+date: 2026-04-25 * Overview yfinance offers a Pythonic way to fetch financial & market data from Yahoo! Finance. ** Installation #+begin_src sh pip install yfinance #+end_src ** Quick Start #+begin_src python 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 #+end_src * 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 #+begin_src python 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, ) #+end_src * Advanced Features ** Logging Enable debug logging: #+begin_src python yf.config.debug.logging = True #+end_src ** 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.