DOCSEARCHbyAlgolia
Submit Docs

yahooquery

repository·master·Indexed 21 days ago

https://github.com/dpguthrie/yahooquery

A Python wrapper for unofficial Yahoo Finance API endpoints, version 2.4.1. It provides tools to retrieve financial data via the Ticker, Screener, and Research classes, as well as standalone functions for currency conversion and market summaries. The library supports asynchronous requests for bulk data retrieval, Pandas DataFrame integration, and access to Yahoo Finance Premium data using Selenium-based login.

Tokens
48K
Snippets
158
Records
171
Agent score
74%

What's inside yahooquery

  1. Combine multiple modules in a single request

    master
    In yahooquery, modules are data accessors that retrieve information from specific Yahoo Finance endpoints. Because these modules are passed as query parameters to the API, you can combine multiple modules into a single request to create a more efficient interface. This allows you to retrieve various datasets (like asset profiles, earnings, or company officers) for a symbol in one go rather than making separate network calls for each.

  2. Combine multiple data modules in a single request

    master
    In yahooquery, data accessors are referred to as modules. Because many modules are retrieved from the same underlying API endpoint, they can be combined as query parameters in a single request. This allows you to create a convenient interface to retrieve multiple types of data (e.g., asset profile, earnings, and company officers) in one network call rather than making separate requests for each.

  3. Use Ticker, Screener, and Research classes for data retrieval

    master

    The yahooquery library provides three primary classes to access different types of Yahoo Finance data. Most data retrieval is performed through these specialized classes:

    • Ticker: Use this class to retrieve company-specific data (e.g., price, fundamentals, financials).
    • Screener: Use this class to retrieve lists of stocks based on specific filtering criteria.
    • Research: Use this class to retrieve proprietary research reports and trade ideas. Note: This class requires a Yahoo Finance Premium subscription.

    All three classes inherit from a base class _YahooFinance, meaning they all support the same set of keyword arguments for configuring asynchronous requests, validating ticker symbols, and retrying failed requests.

  5. Retrieve 30 days of one-minute interval data

    master

    The Yahoo Finance API restricts one-minute (1m) interval data to seven days per request, even though data availability extends to 30 days. To retrieve the last 30 days of one-minute interval data, you must make multiple requests in 7-day ranges.

    In yahooquery, you can achieve this by requesting a 1mo period with a 1m interval; the library will handle making the necessary 4 requests in 7-day ranges to fulfill the request.

    tickers = Ticker('fb aapl nflx', asynchronous=True)

df = tickers.history(period='1mo', interval='1m')

  6. Filter option chain data using MultiIndex

    master

    The DataFrame returned by option_chain uses a MultiIndex with the following levels:

    1. symbol
    2. expiration
    3. optionType

    You can use standard pandas indexing methods to filter the data.

    Common Filtering Tasks:

    • Get specific expiration date for a symbol: df.loc['symbol', 'YYYY-MM-DD']

    • Get specific option type (calls/puts) for an expiration and symbol: df.loc['symbol', 'YYYY-MM-DD', 'calls']

    • Retrieve only calls (or puts) for all symbols: Use .xs() on the appropriate level (level 2 for optionType).

    • Filter by boolean columns (e.g., in-the-money): Combine boolean indexing with .xs() or .loc.

    faang = Ticker('fb aapl amzn nflx goog')
df = faang.option_chain

# Get specific expiration date for specified symbol
df.loc['aapl', '2022-07-31']

# Get specific option type for expiration date for specified symbol
df.loc['aapl', '2022-07-31', 'calls']

# Retrieve only calls for all symbols
df.xs('calls', level=2)

# Only include Apple in the money options
df.loc[df['inTheMoney'] == True].xs('aapl')

  7. Install yahooquery

    master

    Install the base package using pip. If you are a Yahoo Finance Premium subscriber and need to access premium data via Selenium-based login, install the [premium] extra.

    Standard installation:

    pip install yahooquery

    Premium installation (requires Selenium):

    pip install yahooquery[premium]

    You can also use uv for installation:

    uv pip install yahooquery

  9. Create a Ticker instance for single or multiple symbols

    master

    You can initialize a Ticker instance to fetch data for one or many companies.

    • Single symbol: Pass the ticker string directly to Ticker().
    • Multiple symbols (List): Pass a list of ticker strings.
    • Multiple symbols (String): Pass a space-separated string of ticker symbols.

    Note on Request Behavior: Outside of specific properties or methods, each symbol in the instance typically represents an individual request to Yahoo Finance. For example, if you pass 5 symbols and access a property like asset_profile, the library will perform 5 separate API calls.

    # Single symbol
aapl = Ticker('aapl')

# Multiple symbols as a list
symbols_list = ['fb', 'aapl', 'amzn', 'nflx', 'goog']
tickers = Ticker(symbols_list)

# Multiple symbols as a space-separated string
symbols_str = 'fb aapl amzn nflx goog'
tickers = Ticker(symbols_str)

  10. Use the Screener class to retrieve predefined screeners

    master

    The Screener class in yahooquery allows you to access predefined stock screeners from Yahoo Finance.

    Currently, the implementation is limited to retrieving existing predefined screeners. Future updates are expected to support creating custom screeners on the fly and accessing screeners created by users on the Yahoo Finance platform.

    To use this feature, you must:

    1. Import the Screener class.
    2. Create an instance of the Screener class.
    3. Use available_screeners() to see what is available.
    4. Use get_screeners() to retrieve the data for a specific screener.
    from yahooquery import Screener

screener = Screener()
# To see available screeners
print(screener.available_screeners())
# To get data for a specific screener
print(screener.get_screeners('some_screener_id'))

  11. Retrieve predefined screeners with the Screener class

    master

    The Screener class in yahooquery allows you to retrieve predefined stock screeners from Yahoo Finance. Currently, this is limited to predefined screeners; the ability to create custom screeners or use personal Yahoo Finance screeners is planned for future versions.

    To use the screener functionality, you must instantiate the Screener class. You can then use available_screeners() to see what is available and get_screeners() to fetch the actual data for specific screeners.

    from yahooquery import Screener

# Create an instance of the Screener class
screener = Screener()

# Get a list of available screeners
available = screener.available_screeners()

# Retrieve the data for specific screeners
# Example: passing a list of canonical names or IDs
results = screener.get_screeners(['most_actives'])
print(results)

  12. Combine Research and Ticker classes for Premium Subscribers

    master

    If you are a Yahoo Finance Premium subscriber, you can combine the functionalities of the Research class (to find reports or sectors) and the Ticker class (to perform deep analysis on specific symbols) without needing to log in twice.

    To do this, initialize a Research instance with your credentials, then pass the session and crumb attributes from that Research instance into the Ticker constructor. This allows the Ticker instance to reuse the authenticated session established by Research.

    from yahooquery import Research, Ticker

# 1. Authenticate via Research
r = Research(username='username@yahoo.com', password='password')

# 2. Use Research to find data (e.g., reports)
df = r.reports(
    sector='Financial Services',
    report_date='Last Week',
    investment_rating='Bullish',
    report_type='Analyst Report'
)

# 3. Pass Research session and crumb to Ticker to reuse authentication
tickers = Ticker('aapl', session=r.session, crumb=r.crumb)

# Now 'tickers' can access premium data like p_company_360
data = tickers.p_company_360