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¶
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
amountandcurrency. 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,denominatorandsplitRatio(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
amountandcurrency. 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,surprisePercentandcurrency- 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,growthand flattened estimate columns:earningsEstimate_*,revenueEstimate_*,epsTrend_*andepsRevisions_*- 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,sellandstrongSell- 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),valueandpctChange- 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),valueandpctChange- Return type:
DataFrame
- yahoo_api_major_holders()[source]¶
Get the ownership breakdown from Yahoo Finance
Returns:¶
pd.DataFrame: One row per field:
insidersPercentHeld,institutionsPercentHeld,institutionsFloatPercentHeldandinstitutionsCount- 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,positionDirectandpositionDirectDate- 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,valueandownership(“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”),titleandedgarUrl. Theexhibitscolumn 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,holdingNameandholdingPercent(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 aweightcolumn (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,totalNetAssetsand 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 as2025), withfundandcategoryreturn 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,expirationandlastTradeDate(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
- static yahoo_api_search(query, limit=10)[source]¶
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,sectorandindustrywhere availableRaises:¶
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
symboland a relevancescore, 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
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 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
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_lowand52_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): urlform 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