2021-11-21 04:01:04 +08:00
# Download market data from Yahoo! Finance's API
< table border = 1 cellpadding = 10 > < tr > < td >
#### \*\*\* IMPORTANT LEGAL DISCLAIMER \*\*\*
---
2021-11-21 04:13:48 +08:00
2021-11-21 04:01:04 +08:00
**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
2021-11-21 04:13:48 +08:00
details on your rights to use the actual data downloaded. Remember - the
2021-11-21 04:01:04 +08:00
Yahoo! finance API is intended for personal use only.**
< / td > < / tr > < / table >
---
2021-12-30 23:35:43 +08:00
< a target = "new" href = "https://pypi.python.org/pypi/yfinance" > < img border = 0 src = "https://img.shields.io/badge/python-2.7,%203.6+-blue.svg?style=flat" alt = "Python version" > < / a >
2021-11-21 04:50:16 +08:00
< a target = "new" href = "https://pypi.python.org/pypi/yfinance" > < img border = 0 src = "https://img.shields.io/pypi/v/yfinance.svg?maxAge=60%" alt = "PyPi version" > < / a >
< a target = "new" href = "https://pypi.python.org/pypi/yfinance" > < img border = 0 src = "https://img.shields.io/pypi/status/yfinance.svg?maxAge=60" alt = "PyPi status" > < / a >
< a target = "new" href = "https://pypi.python.org/pypi/yfinance" > < img border = 0 src = "https://img.shields.io/pypi/dm/yfinance.svg?maxAge=2592000&label=installs&color=%2327B1FF" alt = "PyPi downloads" > < / a >
< a target = "new" href = "https://travis-ci.com/github/ranaroussi/yfinance" > < img border = 0 src = "https://img.shields.io/travis/ranaroussi/yfinance/main.svg?maxAge=1" alt = "Travis-CI build status" > < / a >
< a target = "new" href = "https://www.codefactor.io/repository/github/ranaroussi/yfinance" > < img border = 0 src = "https://www.codefactor.io/repository/github/ranaroussi/yfinance/badge" alt = "CodeFactor" > < / a >
< a target = "new" href = "https://github.com/ranaroussi/yfinance" > < img border = 0 src = "https://img.shields.io/github/stars/ranaroussi/yfinance.svg?style=social&label=Star&maxAge=60" alt = "Star this repo" > < / a >
< a target = "new" href = "https://twitter.com/aroussi" > < img border = 0 src = "https://img.shields.io/twitter/follow/aroussi.svg?style=social&label=Follow&maxAge=60" alt = "Follow me on twitter" > < / a >
2021-11-21 04:01:04 +08:00
**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:
```python
import yfinance as yf
msft = yf.Ticker("MSFT")
2023-04-06 19:10:04 +08:00
# get all stock info
2021-11-21 04:01:04 +08:00
msft.info
# get historical market data
2023-01-27 22:59:49 +08:00
hist = msft.history(period="1mo")
2021-11-21 04:01:04 +08:00
2022-12-13 00:16:05 +08:00
# show meta information about the history (requires history() to be called first)
msft.history_metadata
2022-11-11 23:27:39 +08:00
# show actions (dividends, splits, capital gains)
2021-11-21 04:01:04 +08:00
msft.actions
msft.dividends
msft.splits
2023-01-27 22:59:49 +08:00
msft.capital_gains # only for mutual funds & etfs
2022-11-11 23:27:39 +08:00
2022-10-17 23:40:12 +08:00
# show share count
2023-01-27 22:59:49 +08:00
msft.get_shares_full(start="2022-01-01", end=None)
2021-11-21 04:01:04 +08:00
2022-12-02 02:49:43 +08:00
# show financials:
2022-12-11 04:59:34 +08:00
# - income statement
2022-10-16 15:34:23 +08:00
msft.income_stmt
msft.quarterly_income_stmt
2022-12-11 04:59:34 +08:00
# - balance sheet
2021-11-21 04:01:04 +08:00
msft.balance_sheet
msft.quarterly_balance_sheet
2022-12-11 04:59:34 +08:00
# - cash flow statement
2021-11-21 04:01:04 +08:00
msft.cashflow
msft.quarterly_cashflow
2022-12-11 04:59:34 +08:00
# see `Ticker.get_income_stmt()` for more options
2021-11-21 04:01:04 +08:00
2023-01-27 22:59:49 +08:00
# show holders
2022-10-16 15:34:23 +08:00
msft.major_holders
msft.institutional_holders
2022-10-17 23:40:12 +08:00
msft.mutualfund_holders
2022-11-20 23:38:49 +08:00
# Show future and historic earnings dates, returns at most next 4 quarters and last 8 quarters by default.
# Note: If more are needed use msft.get_earnings_dates(limit=XX) with increased limit argument.
2022-06-16 00:42:22 +08:00
msft.earnings_dates
2021-11-21 04:01:04 +08:00
# 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")
2022-11-11 23:27:39 +08:00
msft.get_capital_gains(proxy="PROXY_SERVER")
2021-11-21 04:01:04 +08:00
msft.get_balance_sheet(proxy="PROXY_SERVER")
msft.get_cashflow(proxy="PROXY_SERVER")
msft.option_chain(..., proxy="PROXY_SERVER")
...
```
2023-04-07 19:21:01 +08:00
### Multiple tickers
2023-01-29 07:10:38 +08:00
To initialize multiple `Ticker` objects, use
```python
import yfinance as yf
tickers = yf.Tickers('msft aapl goog')
# access each ticker using (example)
tickers.tickers['MSFT'].info
tickers.tickers['AAPL'].history(period="1mo")
tickers.tickers['GOOG'].actions
```
2023-04-07 19:21:01 +08:00
To download price history into one table:
2023-01-29 21:52:13 +08:00
```python
import yfinance as yf
2023-07-07 04:15:41 +08:00
data = yf.download("SPY AAPL", period="1mo")
2023-01-29 21:52:13 +08:00
```
2023-01-29 21:49:01 +08:00
2023-07-07 04:15:41 +08:00
#### `yf.download()` and `Ticker.history()` have many options for configuring fetching and processing. [Review the Wiki](https://github.com/ranaroussi/yfinance/wiki) for more options and detail.
2023-01-29 21:49:01 +08:00
2023-04-11 23:22:19 +08:00
### Logging
2023-06-20 06:25:36 +08:00
`yfinance` now uses the `logging` module to handle messages, default behaviour is only print errors. If debugging, use `yf.enable_debug_mode()` to switch logging to debug with custom formatting.
2023-04-11 23:22:19 +08:00
2023-01-29 07:10:38 +08:00
### Smarter scraping
2021-11-21 04:01:04 +08:00
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'
2022-11-30 06:28:16 +08:00
ticker = yf.Ticker('msft', session=session)
2021-11-21 04:01:04 +08:00
# The scraped response will be stored in the cache
ticker.actions
```
2023-01-29 07:10:38 +08:00
Combine a `requests_cache` with rate-limiting to avoid triggering Yahoo's rate-limiter/blocker that can corrupt data.
2021-11-21 04:01:04 +08:00
```python
2023-01-29 07:10:38 +08:00
from requests import Session
from requests_cache import CacheMixin, SQLiteCache
from requests_ratelimiter import LimiterMixin, MemoryQueueBucket
2023-02-21 20:24:35 +08:00
from pyrate_limiter import Duration, RequestRate, Limiter
2023-01-29 07:10:38 +08:00
class CachedLimiterSession(CacheMixin, LimiterMixin, Session):
2023-02-21 20:24:35 +08:00
pass
2023-01-29 07:10:38 +08:00
session = CachedLimiterSession(
2023-06-03 20:19:31 +08:00
limiter=Limiter(RequestRate(2, Duration.SECOND*5)), # max 2 requests per 5 seconds
2023-01-29 07:10:38 +08:00
bucket_class=MemoryQueueBucket,
backend=SQLiteCache("yfinance.cache"),
)
2021-11-21 04:01:04 +08:00
```
### 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
2023-04-07 19:21:01 +08:00
### `pandas_datareader` override
2021-11-21 04:01:04 +08:00
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")
```
2023-04-07 19:21:01 +08:00
### 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()` :
```python
import yfinance as yf
yf.set_tz_cache_location("custom/cache/location")
...
```
2021-11-21 04:01:04 +08:00
---
## Installation
Install `yfinance` using `pip` :
``` {.sourceCode .bash}
$ pip install yfinance --upgrade --no-cache-dir
```
2023-05-12 19:11:14 +08:00
Test new features by installing betas, provide feedback in [corresponding Discussion ](https://github.com/ranaroussi/yfinance/discussions ):
``` {.sourceCode .bash}
$ pip install yfinance --upgrade --no-cache-dir --pre
```
2021-11-21 04:01:04 +08:00
To install `yfinance` using `conda` , see
[this ](https://anaconda.org/ranaroussi/yfinance ).
### Requirements
- [Python ](https://www.python.org ) \>= 2.7, 3.4+
2022-12-11 02:16:44 +08:00
- [Pandas ](https://github.com/pydata/pandas ) \>= 1.3.0
- [Numpy ](http://www.numpy.org ) \>= 1.16.5
2023-07-21 07:17:44 +08:00
- [requests ](http://docs.python-requests.org/en/master ) \>= 2.31
2022-12-11 02:16:44 +08:00
- [lxml ](https://pypi.org/project/lxml ) \>= 4.9.1
- [appdirs ](https://pypi.org/project/appdirs ) \>= 1.4.4
- [pytz ](https://pypi.org/project/pytz ) \>=2022.5
- [frozendict ](https://pypi.org/project/frozendict ) \>= 2.3.4
- [beautifulsoup4 ](https://pypi.org/project/beautifulsoup4 ) \>= 4.11.1
- [html5lib ](https://pypi.org/project/html5lib ) \>= 1.1
2021-11-21 04:01:04 +08:00
2023-04-07 19:21:01 +08:00
#### Optional (if you want to use `pandas_datareader`)
2021-11-21 04:01:04 +08:00
- [pandas\_datareader ](https://github.com/pydata/pandas-datareader )
\>= 0.4.0
2023-04-07 19:21:01 +08:00
## Developers: want to contribute?
`yfinance` relies on community to investigate bugs and contribute code. Developer guide: https://github.com/ranaroussi/yfinance/discussions/1084
2021-11-21 04:01:04 +08:00
---
### 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**