API reference

Every public method is available on stockdex.Ticker. The classes below are the mixins it is built from, one per data source.

from stockdex import Ticker

stock = Ticker(ticker="AAPL")
etf = Ticker(isin="IE00B4L5Y983", security_type="etf")

Ticker

class stockdex.Ticker(ticker='', isin='', security_type='stock')[source]

Class for the Ticker

Parameters:
  • ticker (str)

  • isin (str)

  • security_type (Literal['stock', 'etf', 'cryptocurrency', 'index', 'commodity'])

Yahoo Finance

class stockdex.yahoo_api_interface.YahooAPI(ticker='', isin='', security_type='stock', data_source='yahoo_api')[source]
Parameters:
  • ticker (str)

  • isin (str)

  • security_type (Literal['stock', 'etf', 'cryptocurrency', 'index', 'commodity'])

  • data_source (Literal['yahoo_api', 'justetf', 'digrin', 'finviz', 'macrotrends', 'nasdaq'])

today = datetime.datetime(2026, 11, 18, 18, 30, 4, 196123)
five_years_ago = datetime.datetime(2021, 11, 18, 18, 30, 4, 196123)
yahoo_api_price(range='1d', dataGranularity='1m')[source]

Get the price data for the stock

Args:

range (str): The range of the price data to retrieve valid values are “1d”, “5d”, “1mo”, “3mo”, “6mo”, “1y”, “2y”, “5y”, “10y”, “ytd”, “max”

dataGranularity (str): The granularity of the data to retrieve (interval) valid values are “1m”, “2m”, “5m”, “15m”, “30m”, “60m”, “90m”, “1h”, “1d”, “5d”, “1wk”, “1mo”, “3mo”” # noqa: E501

Returns:

pd.DataFrame: The price data

Parameters:
  • range (Literal['1d', '5d', '1mo', '3mo', '6mo', '1y', '2y', '5y', '10y', 'ytd', 'max'])

  • dataGranularity (Literal['1m', '2m', '5m', '15m', '30m', '60m', '90m', '1h', '1d', '5d', '1wk', '1mo', '3mo'])

Return type:

DataFrame

property yahoo_api_current_trading_period: DataFrame

Get the current trading period for the stock

yahoo_api_income_statement(frequency='annual', format='fmt', period1=None, period2=None)[source]

Get the income statement for the stock

Args:

frequency (str): The frequency of the data to retrieve valid values are “annual”, “quarterly”

format (str): The format of the data to retrieve valid values are “fmt”, “raw” if “fmt” is used, the data will be in a human readable format, e.g. 1B if “raw” is used, the data will be in a raw format, e.g. 1000000000

period1 (datetime): The start date of the data to retrieve default is five years ago as that is the maximum period the API supports data retrieval for

period2 (datetime): The end date of the data to retrieve default is the current date

Returns:

pd.DataFrame: The income statement data

Parameters:
  • frequency (Literal['annual', 'quarterly'])

  • format (Literal['fmt', 'raw'])

  • period1 (datetime | None)

  • period2 (datetime | None)

Return type:

DataFrame

yahoo_api_cash_flow(frequency='annual', format='fmt', period1=None, period2=None)[source]

Get the cash flow statement for the stock

Args:

frequency (str): The frequency of the data to retrieve valid values are “annual”, “quarterly”

format (str): The format of the data to retrieve valid values are “fmt”, “raw” if “fmt” is used, the data will be in a human readable format, e.g. 1B if “raw” is used, the data will be in a raw format, e.g. 1000000000

period1 (datetime): The start date of the data to retrieve default is five years ago as that is the maximum period the API supports data retrieval for

period2 (datetime): The end date of the data to retrieve default is the current date

Returns:

pd.DataFrame: The cash flow statement data

Parameters:
  • frequency (Literal['annual', 'quarterly'])

  • format (Literal['fmt', 'raw'])

  • period1 (datetime | None)

  • period2 (datetime | None)

Return type:

DataFrame

yahoo_api_balance_sheet(frequency='annual', format='fmt', period1=None, period2=None)[source]

Get the balance sheet for the stock

Args:

frequency (str): The frequency of the data to retrieve valid values are “annual”, “quarterly”

format (str): The format of the data to retrieve valid values are “fmt”, “raw” if “fmt” is used, the data will be in a human readable format, e.g. 1B if “raw” is used, the data will be in a raw format, e.g. 1000000000

period1 (datetime): The start date of the data to retrieve default is five years ago as that is the maximum period the API supports data retrieval for

period2 (datetime): The end date of the data to retrieve default is the current date

Returns:

pd.DataFrame: The balance sheet data

Parameters:
  • frequency (Literal['annual', 'quarterly'])

  • format (Literal['fmt', 'raw'])

  • period1 (datetime | None)

  • period2 (datetime | None)

Return type:

DataFrame

yahoo_api_financials(frequency='annual', format='fmt', period1=None, period2=None)[source]

Get the financials for the stock

Args:

frequency (str): The frequency of the data to retrieve valid values are “annual”, “quarterly”

format (str): The format of the data to retrieve valid values are “fmt”, “raw” if “fmt” is used, the data will be in a human readable format, e.g. 1B if “raw” is used, the data will be in a raw format, e.g. 1000000000

period1 (datetime): The start date of the data to retrieve default is five years ago as that is the maximum period the API supports data retrieval for

period2 (datetime): The end date of the data to retrieve default is the current date

Returns:

pd.DataFrame: The financials data

Parameters:
  • frequency (Literal['annual', 'quarterly'])

  • format (Literal['fmt', 'raw'])

  • period1 (datetime | None)

  • period2 (datetime | None)

Return type:

DataFrame

yahoo_api_valuation_measures(frequency='quarterly', format='fmt', period1=None, period2=None)[source]

Get valuation measures over time for the stock

Columns are market cap, enterprise value, trailing and forward P/E, PEG, price/sales, price/book, EV/revenue and EV/EBITDA, each prefixed with the frequency (e.g. quarterlyPeRatio).

Args:

frequency (str): The frequency of the data to retrieve valid values are “annual”, “quarterly”, “trailing” “trailing” returns recent daily snapshots (trailing twelve months)

format (str): The format of the data to retrieve valid values are “fmt”, “raw” if “fmt” is used, the data will be in a human readable format, e.g. 1B if “raw” is used, the data will be in a raw format, e.g. 1000000000

period1 (datetime): The start date of the data to retrieve default is five years ago

period2 (datetime): The end date of the data to retrieve default is the current date

Returns:

pd.DataFrame: The valuation measures, indexed by as-of date

Parameters:
  • frequency (Literal['annual', 'quarterly', 'trailing'])

  • format (Literal['fmt', 'raw'])

  • period1 (datetime | None)

  • period2 (datetime | None)

Return type:

DataFrame

build_url(frequency, period1, period2, desired_entity)[source]

Build the URL for the income statement, balance sheet, and cash flow statement

Args:

frequency: str

The frequency of the data to retrieve valid values are “annual”, “quarterly”

period1: datetime

The start date of the data to retrieve

period2: datetime

The end date of the data to retrieve

desired_entity: str

The entity to retrieve the data for

Returns:

str: The URL to retrieve the data from

Parameters:
  • frequency (str)

  • period1 (datetime | None)

  • period2 (datetime | None)

  • desired_entity (str)

Return type:

str

extract_dataframe(response, format='fmt')[source]

Extract the dataframes from the response

Args:

response: dict

The response from the API

format: str

The format of the data to retrieve

Returns:

pd.DataFrame: The data in a dataframe

Return type:

DataFrame

yahoo_api_dividends(range='max')[source]

Get the dividend history from Yahoo Finance

Args:

range (str): The range of history to retrieve valid values are “1y”, “2y”, “5y”, “10y”, “ytd”, “max”

Returns:

pd.DataFrame: One row per dividend, indexed by ex-dividend date (UTC), with columns amount and currency. Empty if no dividends were paid.

Parameters:

range (Literal['1y', '2y', '5y', '10y', 'ytd', 'max'])

Return type:

DataFrame

yahoo_api_splits(range='max')[source]

Get the stock split history from Yahoo Finance

Args:

range (str): The range of history to retrieve valid values are “1y”, “2y”, “5y”, “10y”, “ytd”, “max”

Returns:

pd.DataFrame: One row per split, indexed by split date (UTC), with columns numerator, denominator and splitRatio (e.g. “4:1”). Empty if the stock never split.

Parameters:

range (Literal['1y', '2y', '5y', '10y', 'ytd', 'max'])

Return type:

DataFrame

yahoo_api_capital_gains(range='max')[source]

Get capital gain distributions from Yahoo Finance (ETFs and mutual funds)

Args:

range (str): The range of history to retrieve valid values are “1y”, “2y”, “5y”, “10y”, “ytd”, “max”

Returns:

pd.DataFrame: One row per distribution, indexed by date (UTC), with columns amount and currency. Empty for most stocks.

Parameters:

range (Literal['1y', '2y', '5y', '10y', 'ytd', 'max'])

Return type:

DataFrame

yahoo_api_quote_summary(modules, format='raw')[source]

Get one or more modules from Yahoo’s quoteSummary endpoint

This is the building block for the company, analyst, ownership and fund methods. Use it directly to fetch any module listed in stockdex.config.QUOTE_SUMMARY_MODULES.

Args:

modules (str | list): One module name or a list of module names, e.g. "financialData" or ["price", "summaryDetail"]

format (str): “raw” for numbers and epoch timestamps (default), “fmt” for Yahoo’s human readable strings, e.g. “1.2B” or “2026-11-02”

Returns:

dict: Module name to module data. A requested module that Yahoo does not provide for this security is omitted.

Raises:

ValueError: If a module name is not supported

Parameters:
  • modules (str | list)

  • format (Literal['fmt', 'raw'])

Return type:

dict

yahoo_api_profile()[source]

Get the company profile from Yahoo Finance

Returns:

pd.DataFrame: Address, website, sector, industry, number of employees, business summary and governance risk scores, one row per field

Return type:

DataFrame

yahoo_api_officers()[source]

Get the company’s key executives from Yahoo Finance

Returns:

pd.DataFrame: One row per officer with name, title, age, year born, fiscal year and total pay (raw numbers)

Return type:

DataFrame

yahoo_api_market_price(format='raw')[source]

Get the current market price block from Yahoo Finance

Includes regular, pre-market and post-market price and change, market state, currency, exchange and market cap.

Args:

format (str): “raw” for numbers and timestamps, “fmt” for display strings

Returns:

pd.DataFrame: One row per field

Parameters:

format (Literal['fmt', 'raw'])

Return type:

DataFrame

yahoo_api_company_name()[source]

Get the company’s full name from Yahoo Finance

Returns:

str: The long name, e.g. “Apple Inc.”, falling back to the short name and then the ticker

Return type:

str

yahoo_api_summary_detail(format='raw')[source]

Get the quote summary details from Yahoo Finance

Includes previous close, open, day and 52-week ranges, volume, market cap, beta, trailing and forward P/E, dividend rate and yield, and ex-dividend date.

Args:

format (str): “raw” for numbers and timestamps, “fmt” for display strings

Returns:

pd.DataFrame: One row per field

Parameters:

format (Literal['fmt', 'raw'])

Return type:

DataFrame

yahoo_api_key_statistics(format='raw')[source]

Get key statistics from Yahoo Finance

Includes enterprise value, forward P/E, PEG, price/book, shares outstanding and float, short interest, insider and institutional ownership, book value, last split and fiscal year dates.

Args:

format (str): “raw” for numbers and timestamps, “fmt” for display strings

Returns:

pd.DataFrame: One row per field

Parameters:

format (Literal['fmt', 'raw'])

Return type:

DataFrame

yahoo_api_financial_data(format='raw')[source]

Get financial data and analyst price targets from Yahoo Finance

Includes current price, analyst target high/low/mean/median, recommendation, revenue, margins, cash flow, debt, return on equity and growth rates.

Args:

format (str): “raw” for numbers, “fmt” for display strings

Returns:

pd.DataFrame: One row per field

Parameters:

format (Literal['fmt', 'raw'])

Return type:

DataFrame

yahoo_api_calendar_events()[source]

Get upcoming earnings and dividend dates from Yahoo Finance

Returns:

pd.DataFrame: One row per field: next earnings date(s), earnings call date, whether the date is an estimate, EPS and revenue estimate average/low/high, ex-dividend date and dividend payment date

Return type:

DataFrame

yahoo_api_earnings_history()[source]

Get reported vs estimated EPS for the last four quarters

Returns:

pd.DataFrame: One row per quarter, oldest first, with quarter (UTC timestamp), period (e.g. “-4q”), epsActual, epsEstimate, epsDifference, surprisePercent and currency

Return type:

DataFrame

yahoo_api_earnings_trend()[source]

Get analyst EPS and revenue estimates, trend and revisions

Returns:

pd.DataFrame: One row per period (“0q” current quarter, “+1q” next quarter, “0y” current year, “+1y” next year, plus long-term growth), with endDate, growth and flattened estimate columns: earningsEstimate_*, revenueEstimate_*, epsTrend_* and epsRevisions_*

Return type:

DataFrame

yahoo_api_recommendation_trend()[source]

Get analyst recommendation counts for the last few months

Returns:

pd.DataFrame: One row per period (“0m” this month, “-1m” last month, …) with strongBuy, buy, hold, sell and strongSell

Return type:

DataFrame

yahoo_api_upgrades_downgrades()[source]

Get analyst upgrade and downgrade history

Returns:

pd.DataFrame: One row per rating action, newest first, with epochGradeDate (UTC timestamp), firm, fromGrade, toGrade, action (up, down, main, init, reit) and price target changes

Return type:

DataFrame

yahoo_api_institutional_holders()[source]

Get the top institutional holders from Yahoo Finance

Returns:

pd.DataFrame: One row per institution with organization, reportDate (UTC timestamp), pctHeld, position (shares), value and pctChange

Return type:

DataFrame

yahoo_api_fund_holders()[source]

Get the top mutual fund holders from Yahoo Finance

Returns:

pd.DataFrame: One row per fund with organization, reportDate (UTC timestamp), pctHeld, position (shares), value and pctChange

Return type:

DataFrame

yahoo_api_major_holders()[source]

Get the ownership breakdown from Yahoo Finance

Returns:

pd.DataFrame: One row per field: insidersPercentHeld, institutionsPercentHeld, institutionsFloatPercentHeld and institutionsCount

Return type:

DataFrame

yahoo_api_insider_holders()[source]

Get insiders and their direct holdings from Yahoo Finance

Returns:

pd.DataFrame: One row per insider with name, relation, transactionDescription, latestTransDate, positionDirect and positionDirectDate

Return type:

DataFrame

yahoo_api_insider_transactions()[source]

Get recent insider transactions from Yahoo Finance

Returns:

pd.DataFrame: One row per transaction, newest first, with filerName, filerRelation, transactionText, startDate (UTC timestamp), shares, value and ownership (“D” direct, “I” indirect)

Return type:

DataFrame

yahoo_api_insider_purchase_activity()[source]

Get the net insider buying and selling summary from Yahoo Finance

Returns:

pd.DataFrame: One row per field for the reporting period (e.g. “6m”): buy, sell and net transaction counts and shares, percent of insider shares, total insider shares held and net institutional shares bought

Return type:

DataFrame

yahoo_api_sec_filings()[source]

Get recent SEC filings from Yahoo Finance (US-listed companies)

Returns:

pd.DataFrame: One row per filing, newest first, with date, type (e.g. “10-K”, “8-K”), title and edgarUrl. The exhibits column holds the filing’s exhibit links.

Return type:

DataFrame

yahoo_api_fund_top_holdings()[source]

Get the top holdings of an ETF or mutual fund

Returns:

pd.DataFrame: One row per holding with symbol, holdingName and holdingPercent (fraction of the fund, e.g. 0.083 = 8.3%). Empty for individual stocks.

Return type:

DataFrame

yahoo_api_fund_sector_weightings()[source]

Get the sector weightings of an ETF or mutual fund

Returns:

pd.DataFrame: One row per sector (e.g. technology, realestate) with a weight column (fraction of the fund), largest first. Empty for individual stocks.

Return type:

DataFrame

yahoo_api_fund_asset_allocation()[source]

Get the asset class allocation of an ETF or mutual fund

Returns:

pd.DataFrame: One row per position type (stockPosition, bondPosition, cashPosition, preferredPosition, convertiblePosition, otherPosition) with the fraction of the fund. Empty for individual stocks.

Return type:

DataFrame

yahoo_api_fund_profile()[source]

Get the profile and fees of an ETF or mutual fund

Returns:

pd.DataFrame: One row per field: fund family, categoryName, legalType, annualReportExpenseRatio, annualHoldingsTurnover, totalNetAssets and the category averages (suffixed _category). Empty for individual stocks.

Return type:

DataFrame

yahoo_api_fund_performance()[source]

Get trailing and annual total returns of an ETF or mutual fund

Returns:

pd.DataFrame: Rows are periods (ytd, oneMonth, threeMonth, oneYear, threeYear, fiveYear, tenYear, then calendar years such as 2025), with fund and category return columns as fractions (0.15 = 15%). Empty for individual stocks.

Return type:

DataFrame

yahoo_api_option_expirations()[source]

Get the available option expiration dates

Returns:

list: Expiration dates as UTC timestamps, nearest first. Empty if the security has no listed options.

Return type:

list

yahoo_api_options_chain(expiration=None, option_type='both')[source]

Get the options chain for one expiration date

Args:

expiration (str | datetime | None): Expiration date, e.g. “2026-11-20”. Must be one of yahoo_api_option_expirations(). Default is the nearest expiration.

option_type (str): “calls”, “puts” or “both” (default)

Returns:

pd.DataFrame: One row per contract with optionType (“call” or “put”), contractSymbol, strike, lastPrice, bid, ask, change, percentChange, volume, openInterest, impliedVolatility, inTheMoney, expiration and lastTradeDate (UTC timestamps). Empty if there are no options.

Parameters:
  • expiration (str | datetime | None)

  • option_type (Literal['calls', 'puts', 'both'])

Return type:

DataFrame

static yahoo_api_quotes(symbols)[source]

Get current quotes for several symbols in one request

Args:

symbols (str | list): One symbol or a list, e.g. [“AAPL”, “MSFT”]

Returns:

pd.DataFrame: One row per symbol, indexed by symbol, with price, change, volume, market cap, 52-week range, P/E, dividend yield and market state. Symbols Yahoo does not recognise are left out.

Raises:

ValueError: If no symbols are given

Parameters:

symbols (str | list)

Return type:

DataFrame

Search Yahoo Finance for symbols matching a company name or ticker

Args:

query (str): Company name or partial symbol, e.g. “apple” or “BMW” limit (int): Maximum number of results, 1–50 (default 10)

Returns:

pd.DataFrame: Best match first, with symbol, shortname, longname, quoteType (EQUITY, ETF, INDEX, …), exchange, exchDisp, sector and industry where available

Raises:

ValueError: If the query is empty or the limit is out of range

Parameters:
  • query (str)

  • limit (int)

Return type:

DataFrame

yahoo_api_similar_symbols()[source]

Get symbols Yahoo Finance recommends as similar to this one

Returns:

pd.DataFrame: One row per related symbol with symbol and a relevance score, highest first

Return type:

DataFrame

plot_yahoo_api_income_statement(frequency='annual', period1=None, period2=None, group_by='timeframe', fields_to_include=['TotalRevenue', 'EBITDA', 'TotalExpenses', 'NetIncomeCommonStockholders', 'NetIncome'], show_plot=True)[source]

Plots the income statement for the stock using matplotlib grouped bar chart

Parameters:
  • frequency (str) – The frequency of the data to retrieve valid values are “annual”, “quarterly”

  • period1 (datetime) – The start date of the data to retrieve

  • period2 (datetime) – The end date of the data to retrieve

  • group_by (str) – The group by parameter

  • fields_to_include (list) – The fields to include in the chart in the x-axis

  • show_plot (bool) – If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

  • Returns

  • ----------------

  • Union[px.line (The plotly figure)

  • px.bar] (The plotly figure)

Return type:

line | bar

plot_yahoo_api_cash_flow(frequency='annual', period1=None, period2=None, group_by='timeframe', fields_to_include=['OperatingCashFlow', 'FreeCashFlow'], show_plot=True)[source]

Plots the cash flow statement for the stock using matplotlib grouped bar chart

Parameters:
  • frequency (str) – The frequency of the data to retrieve valid values are “annual”, “quarterly”

  • period1 (datetime) – The start date of the data to retrieve

  • period2 (datetime) – The end date of the data to retrieve

  • group_by (str) – The group by parameter

  • fields_to_include (list) – The fields to include in the chart in the x-axis

  • show_plot (bool) – If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

  • Returns

  • ----------------

  • Union[px.line (The plotly figure)

  • px.bar] (The plotly figure)

Return type:

line | bar

plot_yahoo_api_balance_sheet(frequency='annual', period1=None, period2=None, group_by='timeframe', fields_to_include=['TotalAssets', 'TotalDebt'], show_plot=True)[source]

Plots the balance sheet for the stock using matplotlib grouped bar chart

Parameters:
  • frequency (str) – The frequency of the data to retrieve valid values are “annual”, “quarterly”

  • period1 (datetime) – The start date of the data to retrieve

  • period2 (datetime) – The end date of the data to retrieve

  • group_by (str) – The group by parameter

  • fields_to_include (list) – The fields to include in the chart in the x-axis

  • show_plot (bool) – If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

  • Returns

  • ----------------

  • Union[px.line (The plotly figure)

  • px.bar] (The plotly figure)

Return type:

line | bar

plot_yahoo_api_financials(frequency='annual', period1=None, period2=None, group_by='timeframe', fields_to_include=['TotalRevenue', 'EBITDA', 'TotalExpenses', 'NetIncomeCommonStockholders', 'NetIncome'], show_plot=True)[source]

Plots the financials for the stock using matplotlib grouped bar chart

Parameters:
  • frequency (str) – The frequency of the data to retrieve valid values are “annual”, “quarterly”

  • period1 (datetime) – The start date of the data to retrieve

  • period2 (datetime) – The end date of the data to retrieve

  • group_by (str) – The group by parameter

  • fields_to_include (list) – The fields to include in the chart in the x-axis

  • show_plot (bool) – If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

  • Returns

  • ----------------

  • Union[px.line (The plotly figure)

  • px.bar] (The plotly figure)

Return type:

line | bar

Digrin

class stockdex.digrin_interface.DigrinInterface(ticker='', isin='', security_type='stock')[source]
Parameters:
  • ticker (str)

  • isin (str)

  • security_type (Literal['stock', 'etf', 'cryptocurrency', 'index', 'commodity'])

property digrin_dividend: DataFrame

Get dividends for the ticker

Args: period (str): The period for the dividends

Returns: pd.DataFrame: A pandas DataFrame including the dividends visible in the digrin website for the ticker

property digrin_payout_ratio: DataFrame

Get payout ratio for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the payout ratio visible in the digrin website for the ticker

property digrin_price: DataFrame

Get price for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the price visible in the digrin website for the ticker

property digrin_stock_splits: DataFrame

Get stock splits for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the stock splits visible in the digrin website for the ticker

property digrin_assets_vs_liabilities: DataFrame

Get assets vs liabilities for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the assets vs liabilities visible in the digrin website for the ticker

property digrin_free_cash_flow: DataFrame

Get free cash flow for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the free cash flow visible in the digrin website for the ticker

property digrin_net_income: DataFrame

Get net income for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the net income visible in the digrin website for the ticker

property digrin_cash_and_debt: DataFrame

Get cash and debt for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the cash and debt visible in the digrin website for the ticker

property digrin_shares_outstanding: DataFrame

Get shares outstanding for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the shares outstanding visible in the digrin website for the ticker

property digrin_expenses: DataFrame

Get expenses for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the expenses visible in the digrin website for the ticker

property digrin_cost_of_revenue: DataFrame

Get cost of revenue for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the cost of revenue visible in the digrin website for the ticker

property digrin_dgr3: DataFrame

Get dgr3 for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the dgr3 visible in the digrin website for the ticker

property digrin_dgr5: DataFrame

Get dgr5 for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the dgr5 visible in the digrin website for the ticker

property digrin_dgr10: DataFrame

Get dgr10 for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the dgr10 visible in the digrin website for the ticker

property digrin_upcoming_estimated_earnings: DataFrame

Get upcoming estimated earnings for the ticker

Returns: pd.DataFrame: A pandas DataFrame including the upcoming estimated earnings visible in the digrin website for the ticker

plot_digrin_shares_outstanding(show_plot=True)[source]

Plot the shares outstanding for the ticker

Args:

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:

show_plot (bool)

Return type:

line | bar

plot_digrin_price(show_plot=True)[source]

Plot the price for the ticker

Args:

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:

show_plot (bool)

Return type:

line | bar

plot_digrin_dividend(show_plot=True)[source]

Plot the dividend for the ticker

Args:

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:

show_plot (bool)

Return type:

line | bar

plot_digrin_assets_vs_liabilities(show_plot=True)[source]

Plot the assets vs liabilities for the ticker

Args:

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:

show_plot (bool)

Return type:

line | bar

plot_digrin_free_cash_flow(show_plot=True)[source]

Plot the free cash flow for the ticker

Args:

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:

show_plot (bool)

Return type:

line | bar

plot_digrin_net_income(show_plot=True)[source]

Plot the net income for the ticker

Args:

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:

show_plot (bool)

Return type:

line | bar

plot_digrin_cash_and_debt(show_plot=True)[source]

Plot the cash and debt for the ticker

Args:

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:

show_plot (bool)

Return type:

line | bar

plot_digrin_expenses(show_plot=True)[source]

Plot the expenses for the ticker

Args:

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:

show_plot (bool)

Return type:

line | bar

plot_digrin_cost_of_revenue(show_plot=True)[source]

Plot the cost of revenue for the ticker

Args:

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:

show_plot (bool)

Return type:

line | bar

Macrotrends

class stockdex.macrotrends_interface.MacrotrendsInterface(ticker='', isin='', security_type='stock')[source]

Interface for interacting with the Macrotrends website.

Parameters:
  • ticker (str)

  • isin (str)

  • security_type (Literal['stock', 'etf', 'cryptocurrency', 'index', 'commodity'])

property full_name: str

Retrieve the full name of the security as a URL slug, e.g. “apple-inc”

macrotrends_income_statement(frequency='annual')[source]

Retrieve the income statement for the given ticker.

Parameters:

frequency (Literal['quarterly', 'annual'])

Return type:

DataFrame

macrotrends_balance_sheet(frequency='annual')[source]

Retrieve the balance sheet for the given ticker.

Parameters:

frequency (Literal['quarterly', 'annual'])

Return type:

DataFrame

macrotrends_cash_flow(frequency='annual')[source]

Retrieve the cash flow statement for the given ticker.

Parameters:

frequency (Literal['quarterly', 'annual'])

Return type:

DataFrame

property macrotrends_key_financial_ratios: DataFrame

Retrieve the key financial ratios for the given ticker.

property macrotrends_operating_margin: DataFrame

Retrieve the operating margin for the given ticker.

property macrotrends_gross_margin: DataFrame

Retrieve the gross margin for the given ticker.

property macrotrends_ebitda_margin: DataFrame

Retrieve the EBITDA margin for the given ticker.

property macrotrends_pre_tax_margin: DataFrame

Retrieve the pre-tax margin for the given ticker.

property macrotrends_net_margin: DataFrame

Retrieve the net profit margin for the given ticker.

macrotrends_revenue(frequency='annual')[source]

Retrieve the revenue for the given ticker.

Parameters:

frequency (Literal['annual', 'quarterly'])

Return type:

DataFrame

plot_macrotrends_income_statement(fields_to_include=['Revenue', 'Income After Taxes'], frequency='annual', group_by='timeframe', show_plot=True)[source]

Plot the income statement for the given ticker.

Args:

fields_to_includelist

The fields to include in the plot.

frequencyLiteral[“annual”, “quarterly”]

The frequency of the data to plot.

group_byLiteral[“field”, “timeframe”]

The level at which to group the data.

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:
  • fields_to_include (list)

  • frequency (Literal['annual', 'quarterly'])

  • group_by (Literal['field', 'timeframe'])

  • show_plot (bool)

Return type:

line | bar

plot_macrotrends_balance_sheet(fields_to_include=['Cash On Hand', 'Total Assets', 'Total Liabilities'], frequency='annual', group_by='timeframe', show_plot=True)[source]

Plot the balance sheet for the given ticker.

Args:

fields_to_includelist

The fields to include in the plot.

frequencyLiteral[“annual”, “quarterly”]

The frequency of the data to plot.

group_byLiteral[“field”, “timeframe”]

The level at which to group the data.

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:
  • fields_to_include (list)

  • frequency (Literal['annual', 'quarterly'])

  • group_by (Literal['field', 'timeframe'])

  • show_plot (bool)

Return type:

line | bar

plot_macrotrends_cash_flow(fields_to_include=['Net Income/Loss', 'Common Stock Dividends Paid', 'Net Long-Term Debt'], frequency='annual', group_by='timeframe', show_plot=True)[source]

Plot the cash flow statement for the given ticker.

Args:

fields_to_includelist

The fields to include in the plot.

frequencyLiteral[“annual”, “quarterly”]

The frequency of the data to plot.

group_byLiteral[“field”, “timeframe”]

The level at which to group the data.

show_plotbool

If the plot should be shown or not. If dash is used, this should be set to False Default is True (show the plot)

Returns:

Union[px.line, px.bar]: The plotly figure

Parameters:
  • fields_to_include (list)

  • frequency (Literal['annual', 'quarterly'])

  • group_by (Literal['field', 'timeframe'])

  • show_plot (bool)

Return type:

None

Finviz

class stockdex.finviz_interface.FinvizInterface(ticker, isin='', security_type='stock')[source]
Parameters:
  • ticker (str)

  • isin (str)

  • security_type (Literal['stock', 'etf', 'cryptocurrency', 'index', 'commodity'])

finviz_get_insider_trading()[source]

Fetch insider trading data for the specified ticker.

Return type:

DataFrame

finviz_earnings_revisions_data()[source]

Fetch earnings revisions data for the specified ticker

Returns:

DataFrame containing earnings revisions data

Return type:

DataFrame

finviz_earnings_annual_data()[source]

Fetch earnings annual data for the specified ticker

Returns:

DataFrame containing earnings annual data

Return type:

DataFrame

finviz_earnings_data()[source]

Fetch earnings data for the specified ticker

Returns:

DataFrame containing earnings data

Return type:

DataFrame

finviz_overall_dividend()[source]

Fetch overall dividend data for the specified ticker

Returns:

DataFrame containing overall dividend data

Return type:

DataFrame

finviz_dividends_date_data()[source]

Fetch dividend date data for the specified ticker

Returns:

DataFrame containing dividend date data

Return type:

DataFrame

finviz_dividends_annual_data()[source]

Fetch annual dividend data for the specified ticker

Returns:

DataFrame containing annual dividend data

Return type:

DataFrame

finviz_revenue_by_products_and_services()[source]

Fetch revenue by products and services data for the specified ticker

Returns:

a dict of dataframes for each service or product

Return type:

dict

finviz_revenue_by_segment()[source]

Fetch revenue by segment data for the specified ticker

Returns:

a dict of dataframes for each segment

Return type:

dict

finviz_revenue_by_regions()[source]

Fetch revenue by regions data for the specified ticker

Returns:

a dict of dataframes for each region

Return type:

dict

finviz_price_reaction_to_earnings_report()[source]

Fetch price reaction to earnings report data for the specified ticker

Returns:

DataFrame containing price reaction to earnings report data

Return type:

DataFrame

plot_finviz_revenue_by_regions(logarithmic)[source]

Plot revenue by regions data for the specified ticker

Returns:

None

Parameters:

logarithmic (bool)

Return type:

None

plot_finviz_revenue_by_segments(logarithmic)[source]

Plot revenue by segments data for the specified ticker

Returns:

None

Parameters:

logarithmic (bool)

Return type:

None

plot_finviz_revenue_by_products_and_services(logarithmic)[source]

Plot revenue by products and services data for the specified ticker

Returns:

None

Parameters:

logarithmic (bool)

Return type:

None

justETF

class stockdex.justetf_interface.JustETF(ticker='', isin='', security_type='etf')[source]
Parameters:
  • ticker (str)

  • isin (str)

  • security_type (Literal['stock', 'etf', 'cryptocurrency', 'index', 'commodity'])

property justetf_general_info: DataFrame

Get the general information of the ETF genral information includes TER, distribution policy, replication method, etc.

property justetf_wkn: str

Get the identifier justETF shows next to the ISIN

This is the WKN for ETFs listed in Germany; for some ETFs justETF shows the exchange ticker (e.g. IWDA) instead.

property justetf_description: str

Get the description of the ETF

property justetf_basics: DataFrame

Get the baisc information of the ETF

columns may include: - Fund size - Fund domicile - Legal structure - Replication

Returns:

pd.DataFrame: DataFrame containing the basic information of the ETF

property justetf_holdings_companies: DataFrame

Get the top 10 holdings of the ETF by companies

columns may include: - company name - shares in percent

Returns:

pd.DataFrame: DataFrame containing the holdings of the ETF

property justetf_holdings_countries: DataFrame

Get the holdings of the ETF by countries

columns may include: - country name - shares in percent

Returns:

pd.DataFrame: DataFrame containing the holdings of the ETF

property justetf_holdings_sectors: DataFrame

Get the holdings of the ETF by sectors

columns may include: - sector name - shares in percent

Returns:

pd.DataFrame: DataFrame containing the holdings of the ETF

property justetf_price: DataFrame

Get the latest quote of the ETF in EUR

Same as justetf_quote("EUR").

justetf_quote(currency='EUR')[source]

Get the latest quote of the ETF from justETF’s quote API

Args:

currency (str): Currency of the quote, e.g. “EUR”, “USD”, “GBP”, “CHF”

Returns:

pd.DataFrame: One row with the columns in JUSTETF_PRICE_COLUMNS: price, currency, date (YYYY-MM-DD), time (None), exchange, daily_change, daily_change_percent, buy|sell (None), spread (None), previous_close, previous_date, 52_week_low and 52_week_high. Prices are numbers, not localized strings.

Parameters:

currency (str)

Return type:

DataFrame

Charts

class stockdex.sankey_charts.SankeyCharts(ticker)[source]
Parameters:

ticker (str)

plot_sankey_chart(frequency='annual', period_ago=0)[source]

Main function to plot the sankey chart

Args:

frequency: str

The frequency of the data to be used. It can be either “annual” or “quarterly”. Default is “annual”

period_ago: int

The period to go back. Default is 0. if a non zero value, e.g. 3 is provided, the data for 3 periods ago will be used (annual or quarterly based on the frequency)

Returns:

None

Parameters:
  • frequency (Literal['annual', 'quarterly'])

  • period_ago (int)

Return type:

None

stockdex.lib.plot_dataframe(dataframe, title, barmode='group', logaritmic=False, template='plotly', y_axis_title='Amount', x_axis_title='Date', draw_line_chart=False, show_plot=True)[source]

Plot a DataFrame using Plotly Express

Parameters:
  • dataframe (pd.DataFrame) – The DataFrame to plot

  • title (str) – The title of the plot

  • barmode (str) – The barmode of the plot default: “group”

  • logaritmic (bool) – If the y-axis should be logaritmic default: False

  • template (str) – The template of the plot. One of plotly, plotly_white, plotly_dark, ggplot2, seaborn, simple_white, none default: “plotly”#

  • y_axis_title (str) – The title of the y-axis default: “Amount”

  • x_axis_title (str) – The title of the x-axis default: “Date”

  • draw_line_chart (bool) – If the plot should be a line chart and not bar. For charts that have too many data points, it is recommended to use line charts instead of bar charts as it is easier to read. default: False (bar chart)

  • show_plot (bool) – If the plot should be shown. Setting this to False will only return the plot object. Can be used to save the plot to a file or construct complex dashboards with multiple plots. default: True

Return type:

None

Exceptions

Module for custom exceptions

exception stockdex.exceptions.NoISINError(message='No ISIN provided')[source]
Parameters:

message (str)

Return type:

None

exception stockdex.exceptions.NoDataError(message='No data found')[source]
Parameters:

message (str)

Return type:

None

exception stockdex.exceptions.RateLimitError(url, retry_after=None)[source]

Raised when a remote data source responds with HTTP 429.

Parameters:
  • url (str)

  • retry_after (str | None)

Return type:

None

exception stockdex.exceptions.ProviderBlockedError(url, status_code)[source]

Raised when a website keeps refusing the request (HTTP 401 or 403), usually because of bot protection.

The message keeps the Failed to fetch URL (status N): url form so callers that match on the status still work.

Parameters:
  • url (str)

  • status_code (int)

Return type:

None

exception stockdex.exceptions.LayoutChangedError(source, detail)[source]

Raised when a scraped page no longer has the structure Stockdex expects, e.g. a table, header or embedded data block is missing.

This means the website changed, not that the value is zero or absent.

Parameters:
  • source (str)

  • detail (str)

Return type:

None

exception stockdex.exceptions.WrongSecurityType(message='Wrong security type', valid_types=None, given_type=None)[source]

The exception to be shown when a method is called on the wrong security type

Parameters:
  • message (str)

  • valid_types (list)

  • given_type (str)

Return type:

None

exception stockdex.exceptions.WrongDataSource(given_source=None)[source]

The exception to be shown when a method is called on the wrong data source

Parameters:

given_source (str)

Return type:

None

exception stockdex.exceptions.FieldNotExists(available_fields, message='Field does not exist', given_field=None)[source]

The exception to be shown when a field is called that does not exist in the dataframe

Parameters:
  • available_fields (list)

  • message (str)

  • given_field (str)

Return type:

None