286 lines
8.4 KiB
Markdown
286 lines
8.4 KiB
Markdown
|
# Download market data from Yahoo! Finance's API
|
||
|
|
|
||
|
|
<table border=1 cellpadding=10><tr><td>
|
||
|
|
|
||
|
|
#### \*\*\* 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](https://policies.yahoo.com/us/en/yahoo/terms/product-atos/apiforydn/index.htm),
|
||
|
|
[here](https://legal.yahoo.com/us/en/yahoo/terms/otos/index.html), and
|
||
|
|
[here](https://policies.yahoo.com/us/en/yahoo/terms/index.htm)) **for
|
||
|
|
detailes on your rights to use the actual data downloaded. Remember - the
|
||
|
|
Yahoo! finance API is intended for personal use only.**
|
||
|
|
|
||
|
|
</td></tr></table>
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
       
|
||
|
|
|
||
|
|
|
||
|
|
**yfinance** offers a threaded and Pythonic way to download market data from [Yahoo!Ⓡ finance](https://finance.yahoo.com).
|
||
|
|
|
||
|
|
→ Check out this [Blog post](https://aroussi.com/#post/python-yahoo-finance) for a detailed tutorial with code examples.
|
||
|
|
|
||
|
|
[Changelog »](https://github.com/ranaroussi/yfinance/blob/main/CHANGELOG.rst)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Quick Start
|
||
|
|
|
||
|
|
### The Ticker module
|
||
|
|
|
||
|
|
The `Ticker` module, which allows you to access ticker data in a more Pythonic way:
|
||
|
|
|
||
|
|
Note: yahoo finance datetimes are received as UTC.
|
||
|
|
|
||
|
|
```python
|
||
|
|
import yfinance as yf
|
||
|
|
|
||
|
|
msft = yf.Ticker("MSFT")
|
||
|
|
|
||
|
|
# get stock info
|
||
|
|
msft.info
|
||
|
|
|
||
|
|
# get historical market data
|
||
|
|
hist = msft.history(period="max")
|
||
|
|
|
||
|
|
# show actions (dividends, splits)
|
||
|
|
msft.actions
|
||
|
|
|
||
|
|
# show dividends
|
||
|
|
msft.dividends
|
||
|
|
|
||
|
|
# show splits
|
||
|
|
msft.splits
|
||
|
|
|
||
|
|
# show financials
|
||
|
|
msft.financials
|
||
|
|
msft.quarterly_financials
|
||
|
|
|
||
|
|
# show major holders
|
||
|
|
msft.major_holders
|
||
|
|
|
||
|
|
# show institutional holders
|
||
|
|
msft.institutional_holders
|
||
|
|
|
||
|
|
# show balance sheet
|
||
|
|
msft.balance_sheet
|
||
|
|
msft.quarterly_balance_sheet
|
||
|
|
|
||
|
|
# show cashflow
|
||
|
|
msft.cashflow
|
||
|
|
msft.quarterly_cashflow
|
||
|
|
|
||
|
|
# show earnings
|
||
|
|
msft.earnings
|
||
|
|
msft.quarterly_earnings
|
||
|
|
|
||
|
|
# show sustainability
|
||
|
|
msft.sustainability
|
||
|
|
|
||
|
|
# show analysts recommendations
|
||
|
|
msft.recommendations
|
||
|
|
|
||
|
|
# show next event (earnings, etc)
|
||
|
|
msft.calendar
|
||
|
|
|
||
|
|
# show ISIN code - *experimental*
|
||
|
|
# ISIN = International Securities Identification Number
|
||
|
|
msft.isin
|
||
|
|
|
||
|
|
# show options expirations
|
||
|
|
msft.options
|
||
|
|
|
||
|
|
# show news
|
||
|
|
msft.news
|
||
|
|
|
||
|
|
# get option chain for specific expiration
|
||
|
|
opt = 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:
|
||
|
|
|
||
|
|
```python
|
||
|
|
import yfinance as yf
|
||
|
|
|
||
|
|
msft = 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.
|
||
|
|
|
||
|
|
```python
|
||
|
|
import requests_cache
|
||
|
|
session = 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 cache
|
||
|
|
ticker.actions
|
||
|
|
```
|
||
|
|
|
||
|
|
To initialize multiple `Ticker` objects, use
|
||
|
|
|
||
|
|
```python
|
||
|
|
import yfinance as yf
|
||
|
|
|
||
|
|
tickers = yf.Tickers('msft aapl goog')
|
||
|
|
# ^ returns a named tuple of Ticker objects
|
||
|
|
|
||
|
|
# access each ticker using (example)
|
||
|
|
tickers.tickers.MSFT.info
|
||
|
|
tickers.tickers.AAPL.history(period="1mo")
|
||
|
|
tickers.tickers.GOOG.actions
|
||
|
|
```
|
||
|
|
|
||
|
|
### Fetching data for multiple tickers
|
||
|
|
|
||
|
|
```python
|
||
|
|
import yfinance as yf
|
||
|
|
data = yf.download("SPY AAPL", start="2017-01-01", end="2017-04-30")
|
||
|
|
```
|
||
|
|
|
||
|
|
I've also added some options to make life easier :)
|
||
|
|
|
||
|
|
```python
|
||
|
|
data = yf.download( # or pdr.get_data_yahoo(...
|
||
|
|
# tickers list or string as well
|
||
|
|
tickers = "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",
|
||
|
|
|
||
|
|
# 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,
|
||
|
|
|
||
|
|
# 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
|
||
|
|
)
|
||
|
|
```
|
||
|
|
|
||
|
|
### Managing Multi-Level Columns
|
||
|
|
|
||
|
|
The following answer on Stack Overflow is for [How to deal with
|
||
|
|
multi-level column names downloaded with
|
||
|
|
yfinance?](https://stackoverflow.com/questions/63107801)
|
||
|
|
|
||
|
|
- `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()`.
|
||
|
|
|
||
|
|
```python
|
||
|
|
from pandas_datareader import data as pdr
|
||
|
|
|
||
|
|
import yfinance as yf
|
||
|
|
yf.pdr_override() # <== that's all it takes :-)
|
||
|
|
|
||
|
|
# download dataframe
|
||
|
|
data = pdr.get_data_yahoo("SPY", start="2017-01-01", end="2017-04-30")
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Installation
|
||
|
|
|
||
|
|
Install `yfinance` using `pip`:
|
||
|
|
|
||
|
|
``` {.sourceCode .bash}
|
||
|
|
$ pip install yfinance --upgrade --no-cache-dir
|
||
|
|
```
|
||
|
|
|
||
|
|
To install `yfinance` using `conda`, see
|
||
|
|
[this](https://anaconda.org/ranaroussi/yfinance).
|
||
|
|
|
||
|
|
### Requirements
|
||
|
|
|
||
|
|
- [Python](https://www.python.org) \>= 2.7, 3.4+
|
||
|
|
- [Pandas](https://github.com/pydata/pandas) (tested to work with
|
||
|
|
\>=0.23.1)
|
||
|
|
- [Numpy](http://www.numpy.org) \>= 1.11.1
|
||
|
|
- [requests](http://docs.python-requests.org/en/master/) \>= 2.14.2
|
||
|
|
- [lxml](https://pypi.org/project/lxml/) \>= 4.5.1
|
||
|
|
|
||
|
|
### Optional (if you want to use `pandas_datareader`)
|
||
|
|
|
||
|
|
- [pandas\_datareader](https://github.com/pydata/pandas-datareader)
|
||
|
|
\>= 0.4.0
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
### Legal Stuff
|
||
|
|
|
||
|
|
**yfinance** is distributed under the **Apache Software License**. See
|
||
|
|
the [LICENSE.txt](./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](https://policies.yahoo.com/us/en/yahoo/terms/product-atos/apiforydn/index.htm),
|
||
|
|
[here](https://legal.yahoo.com/us/en/yahoo/terms/otos/index.html), and
|
||
|
|
[here](https://policies.yahoo.com/us/en/yahoo/terms/index.htm)) 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**
|