yahooquery

# yahooquery Skill Comprehensive access to Yahoo Finance data via the `yahooquery` Python library. This library provides programmatic access to nearly all Yahoo Finance endpoints, including real-time pricing, fundamentals, analyst estimates, options, news, and premium research. ## Core Classes ### 1. **Ticker** (Company-Specific Data) The primary interface for retrieving data about one or more securities. ```python from yahooquery import Ticker # Single or multiple symbols aapl = Ticker('AAPL') tickers = Ticker('AAPL MSFT NVDA', asynchronous=True) ``` ### 2. **Screener** (Predefined Stock Lists) Access to pre-built screeners for discovering stocks by criteria. ```python from yahooquery import Screener s = Screener() screeners = s.available_screeners # List all available screeners data = s.get_screeners(['day_gainers', 'most_actives'], count=10) ``` ### 3. **Research** (Premium Subscription Required) Access proprietary research reports and trade ideas. ```python 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 Class: Data Modules The `Ticker` class exposes dozens of data endpoints via properties and methods. ### 📊 **Financial Statements** - `.income_statement(frequency='a', trailing=True)` - Income statement (annual/quarterly) - `.balance_sheet(frequency='a', trailing=True)` - Balance sheet - `.cash_flow(frequency='a', trailing=True)` - Cash flow statement - `.all_financial_data(frequency='a')` - Combined financials + valuation measures - `.valuation_measures` - EV/EBITDA, P/E, P/B, P/S across periods ### 📈 **Pricing & Market Data** - `.price` - Current pricing, market cap, 52-week range - `.history(period='1y', interval='1d', start=None, end=None)` - Historical 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` - Full options chain (all expirations) ### 🔍 **Analysis & Estimates** - `.calendar_events` - Next earnings date, EPS/revenue estimates - `.earning_history` - Actual vs. estimated EPS (last 4 quarters) - `.earnings` - Historical quarterly/annual earnings and revenue - `.earnings_trend` - Analyst estimates for upcoming periods - `.recommendation_trend` - Buy/Sell/Hold rating changes over time - `.gradings` - Recent analyst upgrades/downgrades ### 🏢 **Company Fundamentals** - `.asset_profile` - Address, industry, sector, business summary, officers - `.company_officers` - Executives with compensation details - `.summary_profile` - Condensed company information - `.key_stats` - Forward P/E, profit margin, beta, shares outstanding - `.financial_data` - Financial KPIs (ROE, ROA, debt-to-equity, margins) ### 👥 **Ownership & Governance** - `.insider_holders` - List of insider holders and positions - `.insider_transactions` - Recent buy/sell transactions by insiders - `.institution_ownership` - Top institutional holders - `.fund_ownership` - Top mutual fund holders - `.major_holders` - Ownership summary (institutional %, insider %, float) ### 🌍 **ESG & Ratings** - `.esg_scores` - Environmental, Social, Governance scores and controversies - `.recommendation_rating` - Analyst consensus (Strong Buy → Strong Sell) ### 📰 **News & Insights** - `.news()` - Recent news articles - `.technical_insights` - Bullish/bearish technical patterns ### 💰 **Funds & ETFs Only** - `.fund_holding_info` - Top holdings, bond/equity breakdown - `.fund_performance` - Historical performance and returns - `.fund_bond_holdings` / `.fund_bond_ratings` - Bond maturity and credit ratings - `.fund_equity_holdings` - P/E, P/B, P/S for equity holdings ### 📊 **Other Modules** - `.summary_detail` - Trading stats (day high/low, volume, avg volume) - `.default_key_statistics` - Enterprise value, trailing P/E, forward P/E - `.index_trend` - Performance relative to a benchmark index - `.quote_type` - Security type, exchange, market --- ## Global Functions ```python import yahooquery as yq # Search results = yq.search('NVIDIA') # Market Data market = yq.get_market_summary(country='US') # Major indices snapshot trending = yq.get_trending(country='US') # Trending tickers # Utilities currencies = yq.get_currencies() # List of supported currencies exchanges = yq.get_exchanges() # List of exchanges rate = yq.currency_converter('USD', 'EUR') # Exchange rate ``` --- ## Configuration & Keyword Arguments The `Ticker`, `Screener`, and `Research` classes accept these optional parameters: ### Performance & Reliability - `asynchronous=True` - Make requests asynchronously (for multiple symbols) - `max_workers=8` - Number of concurrent workers (when async) - `retry=5` - Number of retry attempts - `backoff_factor=0.3` - Exponential backoff between retries - `status_forcelist=[429, 500, 502, 503, 504]` - HTTP codes to retry - `timeout=5` - Request timeout in seconds ### Data Format & Validation - `formatted=False` - If `True`, returns data with `{raw, fmt, longFmt}` structure - `validate=True` - Validate symbols on instantiation (invalid → `.invalid_symbols`) - `country='United States'` - Regional data/news (france, germany, canada, etc.) ### Network & Auth - `proxies={'http': 'http://proxy:port'}` - HTTP/HTTPS proxy - `user_agent='...'` - Custom user agent string - `verify=True` - SSL certificate verification - `username='you@email.com'` / `password='...'` - Yahoo Finance Premium login ### Advanced (Shared Sessions) - `session=...` / `crumb=...` - Share auth between `Research` and `Ticker` instances --- ## Best Practices ### 1. **Async for Multiple Symbols** ```python tickers = Ticker('AAPL MSFT NVDA TSLA', asynchronous=True) prices = tickers.price # Returns dict keyed by symbol ``` ### 2. **Handling DataFrames** Most financial methods return `pandas.DataFrame`. Convert for JSON output: ```python df = aapl.income_statement() print(df.to_json(orient='records', date_format='iso')) ``` ### 3. **Historical Data - 1-Minute Intervals** Yahoo limits 1-minute data to 7 days per request. For 30 days: ```python tickers = Ticker('AAPL', asynchronous=True) df = tickers.history(period='1mo', interval='1m') # Makes 4 requests automatically ``` ### 4. **Premium Users: Combining Research + Ticker** ```python r = Research(username='...', password='...') reports = r.reports(sector='Technology', investment_rating='Bullish') # Reuse session for Ticker tickers = Ticker('AAPL', session=r.session, crumb=r.crumb) data = tickers.asset_profile ``` --- ## Common Use Cases ### Portfolio Analysis ```python portfolio = Ticker('AAPL MSFT NVDA', asynchronous=True) summary = portfolio.summary_detail earnings = portfolio.earnings history = portfolio.history(period='1y') ``` ### Screening & Discovery ```python s = Screener() gainers = s.get_screeners(['day_gainers'], count=20) # Returns DataFrame with price, volume, % change, etc. ``` ### Options Analysis ```python nvda = Ticker('NVDA') options = nvda.option_chain # Filter for calls/puts, strikes, expirations ``` ### Earnings Calendar ```python tickers = Ticker('AAPL MSFT NVDA') calendar = tickers.calendar_events # Shows next earnings date + analyst estimates ``` --- ## Reference Documentation Full API docs at: `/Users/henryzha/.openclaw/workspace-research/skills/yahooquery/references/` - `index.md` - Overview of classes and functions - `ticker/` - Detailed breakdown of all Ticker methods - `screener.md` - Screener class guide - `research.md` - Research class (Premium) - `keyword_arguments.md` - Complete list of configuration options - `misc.md` - Global utility functions - `advanced.md` - Sharing sessions between Research and Ticker --- ## Environment - **Installation**: `python3 -m pip install yahooquery` - **Dependencies**: pandas, requests-futures, tqdm, beautifulsoup4, lxml - **Python Version**: 3.7+ --- ## Notes - Yahoo Finance may rate-limit or block requests. Use `retry`, `backoff_factor`, and `status_forcelist` for robustness. - Premium features (Research class) require a paid Yahoo Finance Premium subscription. - Data accuracy and availability depend on Yahoo Finance's upstream data providers.