Publish Python Package to PyPI PyPI version
Code style: black Code style: isort flake8
Stockdex is a Python package that provides a simple interface to access financial data from various soruces and plotting capabilities using Plotly.
-
Various data sources:
Stockdexprovides data from Yahoo Finance API and website, Digrin, Macrotrends, and JustETF (for EU ETFs). -
Numerous data categories:
Stockdexprovides various data including financial statements, earnings, dividends, stock splits, list of key executives, major shareholders, and many more. -
Historical data:
Stockdexprovides a wide time range of data, e.g. Digrin and Macrotrends sources, which provide data ranging from 4 years to historical data. -
plotting capabilities (new feature):
Stockdexprovides plotting financial data using bar, line, and sanky plots. Multiple plots can be combined in dash app.
Install the package using pip:
pip install stockdex -U --no-cache-dir
For detailed info about usage of the package and its functions including plotting and dash app, check out the this part of the readme.
In general, to access main functions, The Ticker object should be created with the ticker of the stock as an argument. An example of creating a Ticker object is shown below:
from stockdex import Ticker ticker = Ticker(ticker="AAPL")
The Ticker object provides data from Yahoo Finance API and website, Digrin, and Macrotrends. Below are some of the data that can be retrieved from these sources (more detailed info with output can be found here).
from stockdex import Ticker from datetime import datetime ticker = Ticker(ticker="AAPL") # Price data (use range and dataGranularity to make range and granularity more specific) from Yahoo Finance API price = ticker.yahoo_api_price(range='1y', dataGranularity='1d') # plot financial data using Plotly ticker = Ticker(ticker="MSFT") ticker.plot_yahoo_api_financials(group_by="field") # Complete historical data of the stock in certain categories from digrin website dividend = ticker.digrin_dividend # Financial data from macrotrends website income_statement = ticker.macrotrends_income_statement # Summary including general financial information from Yahoo Finance website summary = ticker.yahoo_web_summary
For EU ETFS, the isin and security_type should be passed to the Ticker object. The isin is the International Securities Identification Number of the ETF and the security_type should be set to etf. Note that justETF has strict rate limiting, so it is recommended to use the data sparingly.
from stockdex import Ticker etf = Ticker(isin="IE00B4L5Y983", security_type="etf") etf_general_info = etf.justetf_general_info
Below you will find available functions based on the source of the data. Each function is prefixed with the source of the data. For example functions with yahoo_api_<function_name> pattern are used to access data from Yahoo Finance API and functions with yahoo_web_<function_name> pattern are used to access data from Yahoo Finance website. Below are some examples of how to access data from different sources.
Functions prefixed with plot will use the plotly library to plot the data. The output of such functions is a plotly figure object. each plot function has a field called show_plot, default value is True, which when set to False will return the plotly figure object instead of showing the plot, this can be helpful plotting multiple figure in dashboards (such as dash). At the end of this document, you will find examples of how to use the functions to build complex dashboards.
Following functions will return the data extracted from Yahoo Finance API in the form of a pandas DataFrame:
from stockdex import Ticker from datetime import datetime ticker = Ticker(ticker="AAPL") # Price data (use range and dataGranularity to make range and granularity more specific) price = ticker.yahoo_api_price(range='1y', dataGranularity='1d') # Current trading period of the stock (pre-market, regular, post-market trading periods) current_trading_period = ticker.yahoo_api_current_trading_period # Fundamental data (use frequency, format, period1 and period2 to fine-tune the returned data) income_statement = ticker.yahoo_api_income_statement(frequency='quarterly') cash_flow = ticker.yahoo_api_cash_flow(format='raw') balance_sheet = ticker.yahoo_api_balance_sheet(period1=datetime(2020, 1, 1)) financials = ticker.yahoo_api_financials(period1=datetime(2022, 1, 1), period2=datetime.today())
Following functions will plot the data extracted from Yahoo Finance API using the plotly library:
from stockdex import Ticker ticker = Ticker(ticker="MSFT") ticker.plot_yahoo_api_financials(group_by="field") ticker.plot_yahoo_api_income_statement(group_by="timeframe") ticker.plot_yahoo_api_cash_flow(freq="quarterly") ticker.plot_yahoo_api_balance_sheet(freq="quarterly")
Running each function will open a tab in default browser showing the plot:
Sankey charts are used to visualize the flow of cash in a company. The plot_sankey_chart function will plot a sankey chart based on data extracted from the Yahoo Finance API. Below is an example of how to plot a sankey chart for AAPL stock:
from stockdex import Ticker ticker = Ticker(ticker="AAPL") ticker.plot_sankey_chart()
The output of the function is a sankey chart showing the income statement of the company. Hovering over the chart will show the amount of cash in each category. Below is the output for AAPL stock based on annual data:
Data on Digrin website includes all historical data of the stock in certain categories, unlike Yahoo Finance which only provides the last 5 years of data at most.
Following functions will return the data extracted from Digrin website in the form of a pandas DataFrame:
from stockdex import Ticker ticker = Ticker(ticker="AAPL") # Complete historical data of the stock in certain categories dividend = ticker.digrin_dividend payout_ratio = ticker.digrin_payout_ratio stock_splits = ticker.digrin_stock_splits price = ticker.digrin_price # Non-historical data assets_vs_liabilities = ticker.digrin_assets_vs_liabilities free_cash_flow = ticker.digrin_free_cash_flow net_income = ticker.digrin_net_income cash_and_debt = ticker.digrin_cash_and_debt shares_outstanding = ticker.digrin_shares_outstanding expenses = ticker.digrin_expenses cost_of_revenue = ticker.digrin_cost_of_revenue upcoming_estimated_earnings = ticker.digrin_upcoming_estimated_earnings # Dividend data dividend = ticker.digrin_dividend dgr3 = ticker.digrin_dgr3 dgr5 = ticker.digrin_dgr5 dgr10 = ticker.digrin_dgr10
Following functions will plot the data extracted from Digrin website using the plotly library:
from stockdex import Ticker ticker = Ticker(ticker="ASML") ticker.plot_digrin_shares_outstanding() ticker.plot_digrin_price() ticker.plot_digrin_dividend() ticker.plot_digrin_assets_vs_liabilities() ticker.plot_digrin_free_cash_flow() ticker.plot_digrin_cash_and_debt() ticker.plot_digrin_net_income() ticker.plot_digrin_expenses() ticker.plot_digrin_cost_of_revenue()
Running each function will open a tab in default browser showing the plot. Below the output for ticker.plot_digrin_cash_and_debt() is illustrated for ASML stock:
Plots with too many data points are plotted as a lie chart, instead of the default bar chart. Below is an example of a line chart for CAT stock historical price:
from stockdex import Ticker
ticker = Ticker(ticker="CAT")
ticker.plot_digrin_price()
The output of the function is a line chart showing the historical price (real and adjusted) of the stock. Below is the output for CAT stock:
Data on Macrotrends website includes historical data in a span years. Below are some of the data that can be retrieved from the Macrotrends website.
Following functions will return the data extracted from Macrotrends website in the form of a pandas DataFrame:
from stockdex import Ticker ticker = Ticker(ticker="AAPL") # Financial data income_statement = ticker.macrotrends_income_statement balance_sheet = ticker.macrotrends_balance_sheet cash_flow = ticker.macrotrends_cash_flow key_financial_ratios = ticker.macrotrends_key_financial_ratios # Margins gross_margin = ticker.macrotrends_gross_margin operating_margin = ticker.macrotrends_operating_margin ebitda_margin = ticker.macrotrends_ebitda_margin pre_tax_margin = ticker.macrotrends_pre_tax_margin net_margin = ticker.macrotrends_net_margin
Following functions will plot the data extracted from Macrotrends website using the plotly library:
from stockdex import Ticker ticker = Ticker(ticker="GOOGL") ticker.plot_macrotrends_income_statement() ticker.plot_macrotrends_balance_sheet() ticker.plot_macrotrends_cash_flow()
Running each function will open a tab in default browser showing the plot. Below the output for ticker.plot_macrotrends_income_statement() is illustrated for GOOGL stock:
from stockdex import Ticker ticker = Ticker(ticker="AAPL") # Summary including general financial information summary = ticker.yahoo_web_summary # Financial data as it is seen in the yahoo finance website income_stmt = ticker.yahoo_web_income_stmt balance_sheet = ticker.yahoo_web_balance_sheet cash_flow = ticker.yahoo_web_cashflow # Analysts and estimates analysis = ticker.yahoo_web_analysis # Data about options calls = ticker.yahoo_web_calls puts = ticker.yahoo_web_puts # Profile data key_executives = ticker.yahoo_web_key_executives description = ticker.yahoo_web_description corporate_governance = ticker.yahoo_web_corporate_governance # Data about shareholders major_holders = ticker.yahoo_web_major_holders top_institutional_holders = ticker.yahoo_web_top_institutional_holders top_mutual_fund_holders = ticker.yahoo_web_top_mutual_fund_holders # Statistics valuation_measures = ticker.yahoo_web_valuation_measures financial_highlights = ticker.yahoo_web_financial_highlights trading_information = ticker.yahoo_web_trading_information
For EU ETFS, the isin and security_type should be passed to the Ticker object. The isin is the International Securities Identification Number of the ETF and the security_type should be set to etf.
from stockdex import Ticker etf = Ticker(isin="IE00B4L5Y983", security_type="etf") etf_general_info = etf.justetf_general_info etf_wkn = etf.justetf_wkn etf_description = etf.justetf_description # Price data and chabges etf_price = etf.justetf_price # Basic data about the ETF etf_basics = etf.justetf_basics # Holdings of the ETF by company, country and sector etf_holdings_companies = etf.justetf_holdings_companies etf_holdings_countries = etf.justetf_holdings_countries etf_holdings_sectors = etf.justetf_holdings_sectors
In previous examples, we have seen how to use the functions with plot_ prefix to create single plots that depict the data. There might be instances where you want to create a dashboard with multiple plots. Below is an example of how to use the functions to create a dashboard with multiple plots using the dash library.
from stockdex.ticker import Ticker from stockdex.lib import plot_multiple_categories # choose the stock ticker = Ticker(ticker="MSFT") # Here you will choose arbitrary figures to plot. In this example we will plot data extracted from digrin website # IMPORTANT: make sure to set show_plot=False in each function to return the plotly figure object instead of showing the plot. Not setting this parameter will show the plots in separate tabs. figures = [ ticker.plot_digrin_shares_outstanding(show_plot=False), ticker.plot_digrin_price(show_plot=False), ticker.plot_digrin_dividend(show_plot=False), ticker.plot_digrin_assets_vs_liabilities(show_plot=False), ticker.plot_digrin_free_cash_flow(show_plot=False), ticker.plot_digrin_net_income(show_plot=False), ticker.plot_digrin_cash_and_debt(show_plot=False), ticker.plot_digrin_expenses(show_plot=False), ticker.plot_digrin_cost_of_revenue(show_plot=False), ] # main functions that will create the dash app plot_multiple_categories(ticker=ticker.ticker, figures=figures)
The output of the above code will be a dashboard on http://127.0.0.1:8050/ by default. The dashboard will have multiple plots showing the data extracted from the Digrin website. Below is the output of the dashboard:
Check out sphinx documentation here for more information about the package.