Download market data from Yahoo! Finance's API

*** IMPORTANT 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 (here, here, and here) for details on your rights to use the actual data downloaded. Remember - the Yahoo! finance API is intended for personal use only.

---

yfinance offers a threaded and Pythonic way to download market data from Yahoo!Ⓡ finance.

→ Check out this Blog post for a detailed tutorial with code examples.

Changelog »

---

Quick Start

The Ticker module

The Ticker module, which allows you to access ticker data in a more Pythonic way:

importyfinanceasyfmsft=yf.Ticker("MSFT")
# get stock infomsft.info# get historical market datahist=msft.history(period="max")
# show actions (dividends, splits)msft.actions# show dividendsmsft.dividends# show splitsmsft.splits# show share countmsft.shares# show income statementmsft.income_stmtmsft.quarterly_income_stmt# show balance sheetmsft.balance_sheetmsft.quarterly_balance_sheet# show cash flow statementmsft.cashflowmsft.quarterly_cashflow# show major holdersmsft.major_holders# show institutional holdersmsft.institutional_holders# show mutualfund holdersmsft.mutualfund_holders# show earningsmsft.earningsmsft.quarterly_earnings# show sustainabilitymsft.sustainability# show analysts recommendationsmsft.recommendationsmsft.recommendations_summary# show analysts other workmsft.analyst_price_targetmfst.revenue_forecastsmfst.earnings_forecastsmfst.earnings_trend# show next event (earnings, etc)msft.calendar# show all earnings datesmsft.earnings_dates# show ISIN code - *experimental*# ISIN = International Securities Identification Numbermsft.isin# show options expirationsmsft.options# show newsmsft.news# get option chain for specific expirationopt=msft.option_chain('YYYY-MM-DD')
# data available via: opt.calls, opt.puts

If you want to use a proxy server for downloading data, use:

importyfinanceasyfmsft=yf.Ticker("MSFT")
msft.history(..., proxy="PROXY_SERVER")
msft.get_actions(proxy="PROXY_SERVER")
msft.get_dividends(proxy="PROXY_SERVER")
msft.get_splits(proxy="PROXY_SERVER")
msft.get_balance_sheet(proxy="PROXY_SERVER")
msft.get_cashflow(proxy="PROXY_SERVER")
msft.option_chain(..., proxy="PROXY_SERVER")
...

To use a custom requests session (for example to cache calls to the API or customize the User-agent header), pass a session= argument to the Ticker constructor.

importrequests_cachesession=requests_cache.CachedSession('yfinance.cache')
session.headers['User-agent'] ='my-program/1.0'ticker=yf.Ticker('msft aapl goog', session=session)
# The scraped response will be stored in the cacheticker.actions

To initialize multiple Ticker objects, use

importyfinanceasyftickers=yf.Tickers('msft aapl goog')
# ^ returns a named tuple of Ticker objects# access each ticker using (example)tickers.tickers['MSFT'].infotickers.tickers['AAPL'].history(period="1mo")
tickers.tickers['GOOG'].actions

Fetching data for multiple tickers

importyfinanceasyfdata=yf.download("SPY AAPL", start="2017-01-01", end="2017-04-30")

I've also added some options to make life easier :)

data=yf.download( # or pdr.get_data_yahoo(...# tickers list or string as welltickers="SPY AAPL MSFT",
# use "period" instead of start/end# valid periods: 1d,5d,1mo,3mo,6mo,1y,2y,5y,10y,ytd,max# (optional, default is '1mo')period="ytd",
# fetch data by interval (including intraday if period < 60 days)# valid intervals: 1m,2m,5m,15m,30m,60m,90m,1h,1d,5d,1wk,1mo,3mo# (optional, default is '1d')interval="1m",
# Whether to ignore timezone when aligning ticker data from # different timezones. Default is True. False may be useful for # minute/hourly data.ignore_tz=False,
# group by ticker (to access via data['SPY'])# (optional, default is 'column')group_by='ticker',
# adjust all OHLC automatically# (optional, default is False)auto_adjust=True,
# identify and attempt repair of currency unit mixups e.g. $/centsrepair=False,
# download pre/post regular market hours data# (optional, default is False)prepost=True,
# use threads for mass downloading? (True/False/Integer)# (optional, default is True)threads=True,
# proxy URL scheme use use when downloading?# (optional, default is None)proxy=None
)

Timezone cache store

When fetching price data, all dates are localized to stock exchange timezone. But timezone retrieval is relatively slow, so yfinance attemps to cache them in your users cache folder. You can direct cache to use a different location with set_tz_cache_location():

importyfinanceasyfyf.set_tz_cache_location("custom/cache/location")
...

Managing Multi-Level Columns

The following answer on Stack Overflow is for How to deal with multi-level column names downloaded with yfinance?

• yfinance returns a pandas.DataFrame with multi-level column names, with a level for the ticker and a level for the stock price data
  • The answer discusses:
    • How to correctly read the the multi-level columns after saving the dataframe to a csv with pandas.DataFrame.to_csv
    • How to download single or multiple tickers into a single dataframe with single level column names and a ticker column

---

pandas_datareader override

If your code uses pandas_datareader and you want to download data faster, you can "hijack" pandas_datareader.data.get_data_yahoo() method to use yfinance while making sure the returned data is in the same format as pandas_datareader's get_data_yahoo().

frompandas_datareaderimportdataaspdrimportyfinanceasyfyf.pdr_override() # <== that's all it takes :-)# download dataframedata=pdr.get_data_yahoo("SPY", start="2017-01-01", end="2017-04-30")

---

Installation

Install yfinance using pip:

$ pip install yfinance --upgrade --no-cache-dir

To install yfinance using conda, see this.

Requirements

• Python >= 2.7, 3.4+
• Pandas (tested to work with >=0.23.1)
• Numpy >= 1.11.1
• requests >= 2.14.2
• lxml >= 4.5.1
• appdirs >=1.4.4

Optional (if you want to use pandas_datareader)

• pandas_datareader >= 0.4.0

---

Legal Stuff

yfinance is distributed under the Apache Software License. See the LICENSE.txt file in the release for details.

AGAIN - 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 (here, here, and here) for detailes on your rights to use the actual data downloaded.

---

P.S.

Please drop me an note with any feedback you have.

Ran Aroussi