yahooquery

name	yahooquery
description	Access Yahoo Finance data including real-time pricing, fundamentals, analyst estimates, options, news, and historical data via the yahooquery Python library.

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.

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.

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.

from yahooquery import Research

r = Research(username='[e-mail]', 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

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='[e-mail]' / password='...' - Yahoo Finance Premium login

Advanced (Shared Sessions)

• session=... / crumb=... - Share auth between Research and Ticker instances

---

Best Practices

1. Async for Multiple Symbols

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:

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:

tickers = Ticker('AAPL', asynchronous=True)
df = tickers.history(period='1mo', interval='1m')  # Makes 4 requests automatically

4. Premium Users: Combining Research + Ticker

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

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

Screening & Discovery

s = Screener()
gainers = s.get_screeners(['day_gainers'], count=20)
# Returns DataFrame with price, volume, % change, etc.

Options Analysis

nvda = Ticker('NVDA')
options = nvda.option_chain
# Filter for calls/puts, strikes, expirations

Earnings Calendar

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.