Download market data from Yahoo! Finance API
Project description
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.
Installation
Install yfinance using pip:
$ pip install yfinance --upgrade --no-cache-dir
To install with optional dependencies, replace optional with: nospam for caching-requests, repair for price repair, or nospam,repair for both:
$ pip install "yfinance[optional]"
Required dependencies , all dependencies.
Quick Start
The Ticker module
The Ticker module, which allows you to access ticker data in a more Pythonic way:
import yfinance as yf
msft = yf.Ticker("MSFT")
# get all stock info
msft.info
# get historical market data
hist = msft.history(period="1mo")
# show meta information about the history (requires history() to be called first)
msft.history_metadata
# show actions (dividends, splits, capital gains)
msft.actions
msft.dividends
msft.splits
msft.capital_gains # only for mutual funds & etfs
# show share count
msft.get_shares_full(start="2022-01-01", end=None)
# show financials:
msft.calendar
msft.sec_filings
# - income statement
msft.income_stmt
msft.quarterly_income_stmt
# - balance sheet
msft.balance_sheet
msft.quarterly_balance_sheet
# - cash flow statement
msft.cashflow
msft.quarterly_cashflow
# see `Ticker.get_income_stmt()` for more options
# show holders
msft.major_holders
msft.institutional_holders
msft.mutualfund_holders
msft.insider_transactions
msft.insider_purchases
msft.insider_roster_holders
msft.sustainability
# show recommendations
msft.recommendations
msft.recommendations_summary
msft.upgrades_downgrades
# show analysts data
msft.analyst_price_targets
msft.earnings_estimate
msft.revenue_estimate
msft.earnings_history
msft.eps_trend
msft.eps_revisions
msft.growth_estimates
# 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.
msft.earnings_dates
# 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
For tickers that are ETFs/Mutual Funds, Ticker.funds_data provides access to fund related data.
Funds' Top Holdings and other data with category average is returned as pd.DataFrame.
import yfinance as yf
spy = yf.Ticker('SPY')
data = spy.funds_data
# show fund description
data.description
# show operational information
data.fund_overview
data.fund_operations
# show holdings related information
data.asset_classes
data.top_holdings
data.equity_holdings
data.bond_holdings
data.bond_ratings
data.sector_weightings
If you want to use a proxy server for downloading data, use:
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_capital_gains(proxy="PROXY_SERVER")
msft.get_balance_sheet(proxy="PROXY_SERVER")
msft.get_cashflow(proxy="PROXY_SERVER")
msft.option_chain(..., proxy="PROXY_SERVER")
...
Multiple tickers
To initialize multiple Ticker objects, use
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
To download price history into one table:
import yfinance as yf
data = yf.download("SPY AAPL", period="1mo")
yf.download() and Ticker.history() have many options for configuring fetching and processing. Review the Wiki for more options and detail.
Sector and Industry
The Sector and Industry modules allow you to access the US market information.
To initialize, use the relevant sector or industry key as below. (Complete mapping of the keys is available in const.py.)
import yfinance as yf
tech = yf.Sector('technology')
software = yf.Industry('software-infrastructure')
# Common information
tech.key
tech.name
tech.symbol
tech.ticker
tech.overview
tech.top_companies
tech.research_reports
# Sector information
tech.top_etfs
tech.top_mutual_funds
tech.industries
# Industry information
software.sector_key
software.sector_name
software.top_performing_companies
software.top_growth_companies
The modules can be chained with Ticker as below.
import yfinance as yf
# Ticker to Sector and Industry
msft = yf.Ticker('MSFT')
tech = yf.Sector(msft.info.get('sectorKey'))
software = yf.Industry(msft.info.get('industryKey'))
# Sector and Industry to Ticker
tech_ticker = tech.ticker
tech_ticker.info
software_ticker = software.ticker
software_ticker.history()
Market Screener
The Screener module allows you to screen the market based on specified queries.
Query Construction
To create a query, you can use the EquityQuery class to construct your filters step by step. The queries support operators: GT (greater than), LT (less than), BTWN (between), EQ (equals), and logical operators AND and OR for combining multiple conditions.
Screener
The Screener class is used to execute the queries and return the filtered results. You can set a custom body for the screener or use predefined configurations.
Logging
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.
Smarter scraping
Install the nospam packages for smarter scraping using pip (see Installation). These packages help cache calls such that Yahoo is not spammed with requests.
To use a custom requests session, pass a session= argument to
the Ticker constructor. This allows for caching calls to the API as well as a custom way to modify requests via the User-agent header.
import requests_cache
session = requests_cache.CachedSession('yfinance.cache')
session.headers['User-agent'] = 'my-program/1.0'
ticker = yf.Ticker('msft', session=session)
# The scraped response will be stored in the cache
ticker.actions
Combine requests_cache with rate-limiting to avoid triggering Yahoo's rate-limiter/blocker that can corrupt data.
from requests import Session
from requests_cache import CacheMixin, SQLiteCache
from requests_ratelimiter import LimiterMixin, MemoryQueueBucket
from pyrate_limiter import Duration, RequestRate, Limiter
class CachedLimiterSession(CacheMixin, LimiterMixin, Session):
pass
session = CachedLimiterSession(
limiter=Limiter(RequestRate(2, Duration.SECOND*5)), # max 2 requests per 5 seconds
bucket_class=MemoryQueueBucket,
backend=SQLiteCache("yfinance.cache"),
)
Managing Multi-Level Columns
The following answer on Stack Overflow is for How to deal with multi-level column names downloaded with yfinance?
yfinancereturns apandas.DataFramewith 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
- How to correctly read the the multi-level columns after
saving the dataframe to a csv with
- The answer discusses:
Persistent cache store
To reduce Yahoo, yfinance store some data locally: timezones to localize dates, and cookie. Cache location is:
- Windows = C:/Users/<USER>/AppData/Local/py-yfinance
- Linux = /home/<USER>/.cache/py-yfinance
- MacOS = /Users/<USER>/Library/Caches/py-yfinance
You can direct cache to use a different location with set_tz_cache_location():
import yfinance as yf
yf.set_tz_cache_location("custom/cache/location")
...
Developers: want to contribute?
yfinance relies on community to investigate bugs and contribute code. Developer guide: https://github.com/ranaroussi/yfinance/discussions/1084
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 details on your rights to use the actual data downloaded.
P.S.
Please drop me an note with any feedback you have.
Ran Aroussi
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file yfinance-0.2.46.tar.gz.
File metadata
- Download URL: yfinance-0.2.46.tar.gz
- Upload date:
- Size: 113.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | a6e2a128915532a54b8f6614cfdb7a8c242d2386e05f95c89b15865b5d9c0352 |
|
| MD5 | 7947a4fbff20665e820f81f25f3482d7 |
|
| BLAKE2b-256 | 0ce294e90f284c775dd7f751ee0155bb91c7958b4d70bc0f9e7e71412be2b3ae |
File details
Details for the file yfinance-0.2.46-py2.py3-none-any.whl.
File metadata
- Download URL: yfinance-0.2.46-py2.py3-none-any.whl
- Upload date:
- Size: 101.0 kB
- Tags: Python 2, Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 371860d532cae76605195678a540e29382bfd0607f8aa61695f753e714916ffc |
|
| MD5 | d28895e88d210a2fb4ee5c263a1fac38 |
|
| BLAKE2b-256 | a21d1a35edd6943f27ff4b5e2d6ba634e7d1bac2e6f815f8efae0666ac71a68d |
