Skip to main content

Retrieve nearly all data from Yahoo Finance for one or more ticker symbols

Project description


CodeFactor PyPi downloads PyPI version PyPI license PyPI pyversions Build Status codecov

Python wrapper around an unofficial Yahoo Finance API.

The blog post contains similar introductory materials as you'll see below, but also has a Jupyter notebook detailing comparisons to yfinance.

2.2.2 Update

  • Bug fix related to the retrieval of income statement and cash flow data. The most recent month and TTM were being combined and returning incorrect data for the last month. The dataframe has been modified to include an additional column called 'periodType'. From that, you'll be able to delineate between quarterly, annual, or trailing 12 month data.

2.0.0 Updates

  • Yahoo Finance Premium data (for subscribed users)
  • Option to make asynchronous and synchronous requests
  • Faster option data retrieval

Table of Contents


pip install yahooquery


The Ticker module is the access point to the Yahoo Finance API. Pass a ticker symbol to the Ticker class.

from yahooquery import Ticker

aapl = Ticker('aapl')

Or pass a list of tickers.

tickers = Ticker(['aapl', 'msft'])

# is equivalent to
tickers = Ticker('aapl msft')

# is equivalent to
tickers = Ticker('aapl, msft')

New to 2.0.0

Additional keyword arguments can be passed to the class to modify certain behavior:

  • asynchronous: Pass asynchronous=True and requests made with multiple symbols will be made asynchronously. Default is False
  • max_workers: Pass max_workers=<n> and modify how many workers are available to make asynchronous requests. This is only used when asynchronous=True is passed as well. Default is 8
  • proxies: Pass proxies={'http': ..., 'https': ...} to use a proxy when making a request. This is recommended when making asynchronous requests.
  • formatted: Pass formatted=True to receive most numeric data in the following form: 'price': {'raw': 126000000000, 'fmt': '$126B'} Default is False
  • username and password: If you subscribe to Yahoo Finance Premium, pass your username and password. You will be logged in and will now be able to access premium properties / methods. All premium properties / methods begin with p_. Disable two-factor authentication for this to work. You do not need to be logged in to access all other properties and methods.


Based on the data you'd like, the result will either be accessed through a dict or as a pandas.DataFrame. Accessing data is incredibly easy and pythonic.


aapl = Ticker('aapl')

# Asset Profile
{'aapl': {'address1': 'One Apple Park Way', 'city': 'Cupertino', ... }}

# ESG Scores
{'aapl': {'totalEsg': 72.27, 'environomentScore': 89.81, ... }}

# Financial Data
{'aapl': {'currentPrice': 275.15, 'targetHighPrice': 342.4, ... }}

# Key Statistics
{'aapl': {'priceHint': 2, 'enterpriseValue': 1230054359040, ... }}

# Price Information
{'aapl': {'preMarketChange': {}, 'preMarketPrice': {}, ... }}

# Quote Type
{'aapl': {'exchange': 'NMS', 'quoteType': 'EQUITY', ... }}

# Share Purchase Activity
{'aapl': {'period': '6m', 'buyInfoCount': 20, ... }}

# Summary Information
{'aapl': {'priceHint': 2, 'previousClose': 271.46, ... }}
{'aapl': {'address1': 'One Apple Park Way', 'city': 'Cupertino', ... }}

How about more than one ticker?

# Pass a list of tickers to the Ticker class
tickers = Ticker('aapl msft')

{'aapl': {'address1': 'One Apple Park Way', 'city': 'Cupertino', ... }, 'msft': {'address1': 'One Microsoft Way', 'city': 'Redmond', ... }}

{'aapl': {'totalEsg': 72.27, 'environomentScore': 89.81, ... }, 'msft': {'totalEsg': 74.8, 'environmentScore': 84.17, ... }}

{'aapl': {'currentPrice': 275.15, 'targetHighPrice': 342.4, ... }, 'msft': {'currentPrice': 154.53, 'targetHighPrice': 174.0, ... }}

{'aapl': {'priceHint': 2, 'enterpriseValue': 1230054359040, ... }, 'msft': {'priceHint': 2, 'enterpriseValue': 1127840350208, ... }}

{'aapl': {'preMarketChange': {}, 'preMarketPrice': {}, ... }, 'msft': {'preMarketChange': {}, 'preMarketPrice': {}, ... }}

{'aapl': {'exchange': 'NMS', 'quoteType': 'EQUITY', ... }, 'msft': {'exchange': 'NMS', 'quoteType': 'EQUITY', ... }}

{'aapl': {'period': '6m', 'buyInfoCount': 20, ... }, 'msft': {'period': '6m', 'buyInfoCount': 30, ... }}

{'aapl': {'priceHint': 2, 'previousClose': 271.46, ... }, 'msft': {'priceHint': 2, 'previousClose': 153.24, ... }}

{'aapl': {'address1': 'One Apple Park Way', 'city': 'Cupertino', ... }, 'msft': {'address1': 'One Microsoft Way', 'city': 'Redmond', ... }}

New in 2.0.0

# News Articles

# Trend data related to a symbols page views

# Top 5 recommended symbols based on a symbol(s)

# Technical trading insights

# Validate symbol's existence



# The following methods take a frequency argument.  If nothing is provided, annual data will be returned.  To return quarterly data, pass "q" as an argument.
aapl.balance_sheet()  # Defaults to Annual



The login functionality utilizes Selenium, and specifically chromedriver, to perform the login. In order for it to work, you need to either add the location to your PATH or extract it to the appropriate default location based on your operating system.

Then, simply pass your login credentials (username and password) when you initialize the Ticker class:

tickers = Ticker('aapl msft fb', username='', password='my_password')

Or you can login after initializing the Ticker class:

tickers.login('', 'my_password')

It will take around 15-20 seconds to log you in. After that, utilize the following properties and methods to retrieve premium data:

# Methods

# The following allows you to retrieve premium reports and ideas related to a given symbol(s).  Report IDs and Idea IDs can be retrieved through the p_portal property

# Properties

Change Symbols

Instead of initializing another class with different symbols, simply do the following:

tickers.symbols = 'goog amzn'
# or
tickers.symbols = ['goog', 'amzn']

Fund Specific

Mutual Funds have many of the accessors detailed above as well as the additional ones below:

fund = Ticker('rpbax')

fund.fund_category_holdings  # pandas.DataFrame
fund.fund_bond_ratings  # pandas.DataFrame
fund.fund_sector_weightings  # pandas.DataFrame
fund.fund_performance  # dict
fund.fund_bond_holdings  # dict
fund.fund_equity_holdings  # dict


Retrieve option pricing for every expiration date for given ticker(s)

import pandas as pd
df = aapl.option_chain  # returns pandas.DataFrame

# The dataframe contains a MultiIndex
FrozenList(['symbol', 'expiration_date', 'option_type', 'row'])

# Get all options for specified symbol

# Get specific expiration date for specified symbol
df.loc['aapl', '2020-01-02']

# Get specific option type for expiration date for specified symbol
df.loc['aapl', '2020-01-02', 'calls']

# Works with multiple tickers as well
tickers = Ticker(['aapl', 'msft', 'fb'])
df = tickers.option_chain

# Retrieve options for only one symbol

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

# Retrieve only puts for fb
df.xs(('fb', 'puts'), level=[0, 2])
# or
df.xs(('fb', 'puts'), level=['symbol', 'option_type'])

# Filter dataframe by options that in the money
df.loc[df['inTheMoney'] == True]

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

Historical Pricing

Historical price data can be retrieved for one or more tickers through the history method.


If no arguments are provided, as above, default values will be supplied for both period and interval, which are ytd and 1d, respectively. Additional arguments you can provide to the method are start and end. Start and end dates can be either strings with a date format of yyyy-mm-dd or as a datetime.datetime object.

aapl.history(start='2019-05-01')  # Default end date is now
aapl.history(end='2018-12-31')  # Default start date is 1900-01-01

# Period options = 1d, 5d, 7d, 60d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max
# Interval options = 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo

Available periods and intervals can be seen through Ticker.PERIODS and Ticker.INTERVALS, respectively.

If trying to retrieve more than one ticker, one dataframe will be returned and the ticker can be accessed in the symbol level of the pandas.MultiIndex.

tickers = Ticker('aapl msft')
symbol date volume open low high close
AAPL 2019-01-02 07:30:00 37039700 154.89 154.23 158.85 157.92
AAPL 2019-01-03 07:30:00 91312200 143.98 142 145.72 142.19
MSFT 2019-12-12 07:30:00 24612100 151.65 151.02 153.44 153.24
MSFT 2019-12-13 14:00:01 23850062 153.003 152.85 154.89 154.53

Multiple Modules

New in 2.0.0

The property and method to retrieve multiple endpoints have changed:

  • from get_endpoints to get_modules
  • from all_endpoints to all_modules

Accessing Multiple Modules

Multiple endpoints can be accessed in one call for a given symbol through two separate modules: get_modules and all_modules. The get_modules method takes in a list or str of allowable modules. Conversely, the all_modules property will retrieve all modules.

aapl = Ticker('aapl')
modules = ['assetProfile', 'esgScores', 'incomeStatementHistory']
# or
modules = ['assetProfile esgScores incomeStatementHistory']
data = aapl.get_modules(modules)

# or

data = aapl.all_modules

# The symbol(s) and modules become the keys in the dictionary



  • The data will always be returned as a dictionary
  • Ticker.MODULES will show you the list of allowable modules you can pass to the get_modules method


The Screener class is the access point to retrieve predefined Yahoo Finance lists (most actives, cryptocurrencies, day gainers, day losers, etc.). It's also simple to use.

from yahooquery import Screener

s = Screener()

View list of available predefined lists from Yahoo Finance

# View available screeners along with description and nice name

# or just view list of keys

Then pass a key to the get_screeners function on the Screener instance:

# Stocks ordered in descending order by intraday trade volume 
data = s.get_screeners('most_actives')

# Pass a number of quotes to return, default is 25
data = s.get_screeners('most_actives', count=10)

Data will be returned as a dictionary:


The list will be in the quotes key:


Or pass a list of multiple keys:

data = s.get_screeners(['most_actives', 'day_gainers', 'day_losers'])

# is equivalent to
data = s.get_screeners('most_actives day_gainers day_losers')



The Research class is the access point to retrieve either research reports or trade ideas from Yahoo Finance. You must be a subscriber to Yahoo Finance Premium to utilize this class.

from yahooquery import Research

r = Research(username='', password='my_password')

It's important to note that all keyword arguments that you can pass to the Ticker class are available in the Research class as well.

r = Research(username='', password='my_password', asynchronous=True, formatted=True)

After initializing the class though, retrieving data is incredibly simple.

# Retrieve research reports

# Retrieve trade ideas

Both functions allow for filtering as well as increasing the number of results returned.


# Each method takes a size argument that determines the amount of reports or trade ideas returned

Requests are made in batches of 100



  • investment_rating: see Research.TRENDS['options'] for available options
  • sector: see Research.SECTORS['options'] for available options
  • report_type: see Research.REPORT_TYPES['options'] for available options
  • report_date: see Research.DATES['options'] for available options
# Filter by sectors
r.reports(sector=['Basic Materials', 'Real Estate'])

# is equivalent to
r.reports(sector='Basic Materials, Real Estate')

# Combine filters
r.reports(25, sector='Basic Materials', report_date='Last Week', investment_rating=['Bearish', 'Bullish'])

Trade Ideas

  • trend: see Research.TRENDS['options'] for available options
  • sector: see Research.SECTORS['options'] for available options
  • term: see Research.TERMS['options'] for available options
  • startdatetime: see Research.DATES['options'] for available options
# Filter by sectors
r.trades(sector=['Basic Materials', 'Real Estate'])

# is equivalent to
r.trades(sector='Basic Materials, Real Estate')

# Combine filters
r.trades(25, sector='Basic Materials', startdatetime='Last Week', trend=['Bearish', 'Bullish'])

Advanced Usage

FOR YAHOO FINANCE PREMIUM SUBSCRIBERS: There might be a use case for combining the functionalities of both the Ticker and Research class. And, ideally, the user wouldn't have to utilize the login functionality in both instances. Here's how you would do that:

from yahooquery import Research, Ticker

r = Research(username='', password='my_password', asynchronous=True)

# I want to retrieve last week's Bullish Analyst Report's for the Financial Services sector
df = r.reports(sector='Financial Services', report_date='Last Week', investment_rating='Bullish', report_type='Analyst Report')

# But now I want to get the data I find relevant and run my own analysis

# Using aapl as a default symbol (we will change that later).  But, the important part is passing the current session and crumb from our Research instance
tickers = Ticker('aapl', session=r.session, crumb=r.crumb)

# Now, I can loop through the dataframe and retrieve relevant data for each ticker within the dataframe utilizing the Ticker instance
for i, row in df.iterrows():
    tickers.symbols = row['Tickers']
    data = tickers.p_company_360
    # Do something with data
    # ...

# Or, pass all tickers to the Ticker instance
ticker_list = df['Tickers'].tolist()
ticker_list = list(set(_flatten_list(ticker_list)))
tickers = Ticker(ticker_list, session=r.session, crumb=r.crumb)
data = tickers.p_company_360
# Do something with data
# ...

Miscellaneous Functions

Additional data can be obtained from Yahoo Finance outside of the Ticker class. The following functions can be utilized to retrieve additional data unrelated to a ticker symbol:

from yahooquery import get_currencies, get_market_summary, get_trending

They take in keyword arguments of lang, region, and corsDomain. The defaults are as follows:

default = {
    'lang': 'en-US',
    'region': 'US',
    'corsDomain': ''

Those defaults, or keyword arguments, are used as query parameters in the requests made to Yahoo Finance.

# Obtain a list of all currencies
d = get_currencies()

# View market summary statistics
d = get_market_summary()

# View trending tickers for a region (default is 'US')
d = get_trending()

One more function allows you to view a list of exchanges Yahoo Finance supports. It takes no arguments or keyword arguments and returns a pandas.DataFrame.

from yahooquery import get_exchanges

df = get_exchanges()

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for yahooquery, version 2.2.5
Filename, size File type Python version Upload date Hashes
Filename, size yahooquery-2.2.5.tar.gz (53.2 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page