Documentation

This page includes all the documentation for the Finance Toolkit, an open-source toolkit in which all relevant financial methods (500+) are written down in the most simplistic way allowing for complete transparency of the calculation method. Each functionality includes an example of how to use it and is therefore an excellent way to better understand how to use each functionality. These examples are also directly embedded in the code. For simplicity sake, only the controller modules are included here given that the models themselves should be relatively straightforward. Make sure to also have a look at the example notebooks as found here.

The Toolkit Module is a collection of functions that collect and parse data, including historical data, fundamental data (balance, income and cash flow statements) and metrics from Financial Modeling Prep such as enterprise values, company profiles and more. From this module you can access all related sub-modules.

To install the FinanceToolkit it simply requires the following:

pip install financetoolkit -U

ratios

The Ratios Module contains over 50+ ratios that can be used to analyse companies. These ratios are divided into 5 categories which are efficiency, liquidity, profitability, solvency and valuation. Each ratio is calculated using the data from the Toolkit module.

Some examples of ratios are the Current Ratio, Debt to Equity Ratio, Return on Assets (ROA), Return on Equity (ROE), Return on Invested Capital (ROIC), Return on Capital Employed (ROCE), Price to Earnings Ratio (P/E), Price to Book Ratio (P/B), Price to Sales Ratio (P/S), Price to Cash Flow Ratio (P/CF), Price to Free Cash Flow Ratio (P/FCF), Dividend Yield and Dividend Payout Ratio.

Next to that, it is also possible to define custom ratios.

See the following link for more information: https://www.jeroenbouma.com/projects/financetoolkit/docs/ratios

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

profitability_ratios = toolkit.ratios.collect_profitability_ratios()

profitability_ratios.loc['AAPL']

Which returns:

models

Gives access to the Models module. The Models module is meant to execute well-known models such as DUPONT and the Discounted Cash Flow (DCF) model. These models are also directly related to the data retrieved from the Toolkit module.

See the following link for more information: https://www.jeroenbouma.com/projects/financetoolkit/docs/models

from financetoolkit import Toolkit

toolkit = Toolkit(["TSLA", "AMZN"], api_key="FINANCIAL_MODELING_PREP_KEY", quarterly=True, start_date='2022-12-31')

dupont_analysis = toolkit.models.get_extended_dupont_analysis()

dupont_analysis.loc['AMZN']

Which returns:

options

This gives access to the Options module. The Options Module is meant to provide Options valuations based on real market data. This includes the Black-Scholes model and in the future the Binomial model and the Monte Carlo model. It also includes all available first-order, second-order and third-order Greeks such as Delta, Gamma, Theta, Vega, Rho, Charm, Vanna, Vomma, Veta, Speed and Zomma.

It gives insights in the sensitivity of an option to changes in the underlying asset price, volatility, years to maturity, dividend yilds and interest rates and several derivatives of these sensitivities.

See the following link for more information: https://www.jeroenbouma.com/projects/financetoolkit/docs/options

from financetoolkit import Toolkit

toolkit = Toolkit(["TSLA", "MU"], api_key="FINANCIAL_MODELING_PREP_KEY")

all_greeks = toolkit.options.collect_all_greeks(start_date='2024-01-03')

all_greeks.loc['TSLA', '2024-01-04']

Which returns:

technicals

This gives access to the Technicals module. The Technicals Module contains nearly 50 Technical Indicators that can be used to analyse companies. These indicators are divided into 3 categories: breadth, overlap and volatility. Each indicator is calculated using the data from the Toolkit module.

Some examples of technical indicators are the Average Directional Index (ADX), the Accumulation/Distribution Line (ADL), the Average True Range (ATR), the Bollinger Bands (BBANDS), the Commodity Channel Index (CCI), the Chaikin Oscillator (CHO), the Chaikin Money Flow (CMF), the Double Exponential Moving Average (DEMA), the Exponential Moving Average (EMA) and the Moving Average Convergence Divergence (MACD).

See the following link for more information: https://www.jeroenbouma.com/projects/financetoolkit/docs/technicals

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

average_directional_index = toolkit.technicals.get_average_directional_index()

Which returns:

performance

This gives access to the Performance module. The Performance Module is meant to calculate metrics related to the risk-return relationship. These are things such as Beta, Sharpe Ratio, Sortino Ratio, CAPM, Alpha and the Treynor Ratio.

It gives insights in the performance a stock has to e.g. a benchmark that is not easily identified by looking at the raw data. This class is closely related to the Risk class which highlights things such as Value at Risk (VaR) and Maximum Drawdown.

See the following link for more information: https://www.jeroenbouma.com/projects/financetoolkit/docs/performance

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.performance.get_capital_asset_pricing_model(period='quarterly')

Which returns:

risk

This gives access to the Risk module. The Risk Module is meant to calculate metrics related to risk such as Value at Risk (VaR), Conditional Value at Risk (cVaR), EMWA/GARCH models and similar models. It also houses cross-asset systemic risk and liquidity measures (CoVaR, Tail Dependence, Amihud Illiquidity, Roll Spread).

Note that the time-series diagnostic and econometric tests (unit root tests, cointegration, Granger causality, ARCH-LM, Jarque-Bera and similar tests) live in the separate Econometrics module instead.

It gives insights in the risk a stock composes that is not perceived as easily by looking at the data. This class is closely related to the Performance class which highlights things such as Sharpe Ratio and Sortino Ratio.

See the following link for more information: https://www.jeroenbouma.com/projects/financetoolkit/docs/risk

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.risk.get_value_at_risk(period='yearly')

Which returns:

econometrics

This gives access to the Econometrics module, a thin wrapper that funnels this Toolkit’s price/return data through statsmodels and linearmodels – regression (OLS/WLS/GLS/ Logit/Probit/Quantile), panel data (Fixed/Random Effects, Hausman), causal inference (IV-2SLS, Difference-in-Differences, Regression Discontinuity, Propensity Score Matching), specification/hypothesis tests (Breusch-Pagan, White, Durbin-Watson, VIF, RESET, Chow, t/F/LR/Wald tests), stationarity (Augmented Dickey-Fuller, KPSS, Phillips-Perron, Zivot-Andrews unit root tests), long-run equilibrium relationships (Engle-Granger and Johansen cointegration), predictive lead-lag relationships (Granger causality), model/ residual diagnostics (ARCH-LM, Jarque-Bera, Ljung-Box, Variance Ratio, CUSUM), forecast comparison (Diebold-Mariano), and time series forecasting (ARIMA, VAR, VECM).

This class is closely related to the Risk class, which houses the risk measures (VaR, CVaR, GARCH) that these tests often inform the choice of.

Requires the optional financetoolkit[econometrics] extra (statsmodels and linearmodels) – install with pip install financetoolkit[econometrics].

See the following link for more information: https://www.jeroenbouma.com/projects/financetoolkit/docs/econometrics

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.econometrics.get_augmented_dickey_fuller(period='yearly')

fixedincome

This gives access to the Fixed Income module. This module contains a wide variety of fixed income related calculations such as the Effective Yield, the Macaulay Duration, the Modified Duration, the Convexity, the Yield to Maturity and models such as Black and Bachelier to valuate derivative instruments such as Swaptions.

Next to that, it is also possible to acquire Central Bank Rates and ICE BofA Indices such as the ICE BofA US High Yield Index, the ICE BofA US Corporate Index and the ICE BofA US Treasury Index.

Note that this class can also be directly accessed by importing the FixedIncome class directly via from financetoolkit import FixedIncome. This is useful if you only want to use the FixedIncome class and not the other classes within the Toolkit module.

See the following link for more information: https://www.jeroenbouma.com/projects/financetoolkit/docs/fixedincome

from financetoolkit import FixedIncome

fixedincome = FixedIncome(
    start_date='2024-01-01',
    end_date='2024-01-15',
)

fixedincome.get_effective_yield(maturity=False)

Which returns:

economics

This gives access to the Economics module. This module contains a wide variety of economic data obtained from OECD. These include things such as the Consumer Price Index (CPI), the Producer Price Index (PPI), the Unemployment Rate, the GDP Growth Rate, the Long and Short Term Interest Rate and the Consumer Confidence Index.

Note that this class can also be directly accessed by importing the Economics class directly via from financetoolkit import Economics. This is useful if you only want to use the Economics class and not the other classes within the Toolkit module.

See the following link for more information: https://www.jeroenbouma.com/projects/financetoolkit/docs/economics

from financetoolkit import Toolkit

toolkit = Toolkit(["AMZN", "ASML"])

cpi = toolkit.economics.get_consumer_price_index(period='yearly')

cpi.loc['2015':, ['United States', 'Netherlands', 'Japan']]

Which returns:

get_profile

Obtain the profile of the specified tickers. These include important metrics such as the beta, market capitalization, currency, isin, industry, and ipo date that give an overall understanding about the company.

Also known as: company description, sector, industry, CEO, employee count.

Args:

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["MSFT", "AAPL"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.get_profile()

Which returns:

get_quote

Get the quote of the specified tickers. These include important metrics such as the price, changes, day low, day high, year low, year high, market capitalization, volume, average volume, open, previous close, earnings per share (EPS), price to earnings ratio (PE), earnings announcement, shares outstanding and timestamp that give an overall understanding about the company.

Also known as: real-time price, current stock price, live quote.

Args:

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["TSLA", "AAPL"], api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.get_quote()

Which returns:

get_rating

Get the rating of the specified tickers. These scores and recommendations are categorized as follows:

• An overall rating

• Discounted Cash Flow (DCF)

• Return on Equity (ROE)

• Return on Assets (ROA)

• Debt to Equity (DE)

• Price Earnings (PE)

• Price to Book (PB)

Also known as: analyst consensus, buy sell hold recommendation.

Args:

Raises:

ValueError: If an API key is not defined for FinancialModelingPrep.

Returns:

pd.DataFrame: The stock rating information for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AMZN", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

rating = toolkit.get_rating()

rating.loc['AMZN'].tail()

Which returns:

get_analyst_estimates

Obtain analyst estimates regarding revenues, EBITDA, EBIT, Net Income SGA Expenses and EPS. The number of analysts are also reported.

Note that this information requires a Premium FMP subscription.

Also known as: earnings estimates, revenue estimates, analyst consensus.

Args:

• overwrite (bool, optional): Defines whether to overwrite the existing data. Defaults to False.
• rounding (int \| None, optional): Defines the number of decimal places to round the data to. Defaults to None.
• growth (bool, optional): Defines whether to return the growth of the data. Defaults to False.
• lag (int \| list[int], optional): Defines the number of periods to lag the growth data by. Defaults to 1.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pandas.DataFrame: The analyst estimates for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(
    ["AAPL", "MSFT", "GOOGL", "AMZN"], api_key="FINANCIAL_MODELING_PREP_KEY", start_date="2024-05-01", quarterly=False
)

analyst_estimates = toolkit.get_analyst_estimates()

analyst_estimates.loc['AAPL'].iloc[:, :5]

Which returns:

get_earnings_calendar

Obtain Earnings Calendars for any range of companies. You have the option to obtain the actual dates or to convert to the corresponding quarters.

Note that this information requires a Premium FMP subscription.

Also known as: earnings dates, earnings schedule, reporting date.

Args:

• actual_dates (bool): Defines whether to return the actual dates or the corresponding quarters.
• overwrite (bool): Defines whether to overwrite the existing data.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.
• rounding (int \| None): The number of decimals to round the results to. Defaults to None, which uses the rounding set on the Toolkit.

Returns:

pd.DataFrame: The earnings calendar for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(
    ["AAPL", "MSFT", "GOOGL", "AMZN"], api_key="FINANCIAL_MODELING_PREP_KEY", start_date="2022-08-01", quarterly=False
)

earning_calendar = toolkit.get_earnings_calendar()

earning_calendar.loc['AMZN']

Which returns:

get_stock_news

Obtain the latest stock market news articles for the tickers of this Toolkit instance. Qualitative companion to the toolkit’s quantitative data. Automatically filtered to this Toolkit instance’s start_date and end_date.

Also known as: ticker news, company news feed.

Args:

• pages (int, optional): The number of pages to collect, each page is a separate API call, e.g. pages=5 makes 5 calls. Defaults to 1.
• limit (int, optional): The number of articles to return per page. Defaults to 100.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pd.DataFrame: The latest news articles for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "MSFT"], api_key="FINANCIAL_MODELING_PREP_KEY")

stock_news = toolkit.get_stock_news(limit=5)

stock_news[["Symbol", "Publisher", "Title"]]

Which returns:

get_press_releases

Obtain the latest official company press releases for the tickers of this Toolkit instance, such as earnings announcements and corporate communications. Automatically filtered to this Toolkit instance’s start_date and end_date.

Also known as: corporate announcements, company press release feed.

Args:

• pages (int, optional): The number of pages to collect, each page is a separate API call, e.g. pages=5 makes 5 calls. Defaults to 1.
• limit (int, optional): The number of articles to return per page. Defaults to 100.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pd.DataFrame: The latest press releases for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "MSFT"], api_key="FINANCIAL_MODELING_PREP_KEY")

press_releases = toolkit.get_press_releases(limit=5)

press_releases[["Symbol", "Publisher", "Title"]]

Which returns:

get_revenue_geographic_segmentation

Obtain revenue by geographic segmentation (e.g. United States, Europe, Asia).

Note that this information requires a Premium FMP subscription.

Also known as: revenue by region, geographic revenue breakdown.

Args:

• overwrite (bool): Defines whether to overwrite the existing data.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pd.DataFrame: The revenue by geographic segmentation for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(
    ["AAPL", "MSFT", "GOOGL", "AMZN"], api_key="FINANCIAL_MODELING_PREP_KEY", start_date="2021-05-01", quarterly=False
)

geographic_segmentation = toolkit.get_revenue_geographic_segmentation()

geographic_segmentation.loc['AAPL']

Which returns:

get_revenue_product_segmentation

Obtain revenue by product segmentation (e.g. iPad, Advertisement, Windows).

Note that this information requires a Premium FMP subscription.

Also known as: revenue by product, product segment revenue.

Args:

• overwrite (bool): Defines whether to overwrite the existing data.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pd.DataFrame: The revenue by product segmentation for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(
    ["AAPL", "MSFT", "GOOGL", "AMZN"], api_key="FINANCIAL_MODELING_PREP_KEY", start_date="2021-05-01", quarterly=False
)

product_segmentation = toolkit.get_revenue_product_segmentation()

product_segmentation.loc['MSFT']

Which returns:

get_historical_data

Returns historical data for the specified tickers. This contains the following columns: - Open: The opening price for the period. - High: The highest price for the period. - Low: The lowest price for the period. - Close: The closing price for the period. - Adj Close: The adjusted closing price for the period. - Volume: The volume for the period. - Dividends: The dividends for the period. - Return: The return for the period. - Cumulative Return: The cumulative return for the period.

Volatility, Excess Return and Excess Volatility are not included here. These are available as dedicated calculations in the Risk module (e.g. toolkit.risk.get_volatility, toolkit.risk.get_excess_volatility) and the Performance module (e.g. toolkit.performance.get_excess_return) instead.

If a benchmark ticker is selected, it also calculates the benchmark ticker together with the results. By default this is set to “SPY” (S&P 500 Index) but can be any ticker. This is relevant for calculations for models such as CAPM, Alpha and Beta.

Important to note is that when an api_key is included in the Toolkit initialization that the data collection defaults to FinancialModelingPrep which is a more stable source and utilises your subscription. However, if this is undesired, it can be disabled by setting enforce_source to “YahooFinance”. If data collection fails from FinancialModelingPrep it automatically reverts back to YahooFinance.

Also known as: OHLCV, price history, open high low close volume.

Args:

• enforce_source (str, optional): A string containing the historical source you wish to enforce. This can be either FinancialModelingPrep or YahooFinance. Defaults to no enforcement.
• period (str): The interval at which the historical data should be returned - daily, weekly, monthly, quarterly, or yearly. Defaults to “daily”.
• return_column (str): The column to use for the return calculation. Defaults to “Adj Close”.
• include_dividends (bool): Defines whether to include dividends in the return calculation. Defaults to True.
• fill_nan (bool): Defines whether to forward fill NaN values. This defaults to True to prevent holes in the dataset. This is especially relevant for technical indicators.
• overwrite (bool): Defines whether to overwrite the existing data. If this is not enabled, the function will return the earlier retrieved data. This is done to prevent too many API calls. Defaults to False.
• rounding (int): Defines the number of decimal places to round the data to.
• show_ticker_seperation (bool, optional): A boolean representing whether to show which tickers acquired data from FinancialModelingPrep and which tickers acquired data from YahooFinance.
• show_columns (list[str], optional): A list of columns to include in the output. Valid columns are Open, High, Low, Close, Adj Close, Volume, Dividends, Return and Cumulative Return. Invalid column names are logged as warnings. If all provided columns are invalid the full dataset is returned. Defaults to None (all columns).

Raises:

ValueError: If an invalid value is specified for period.

Returns:

pandas.DataFrame: The historical data for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit("AAPL", api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.get_historical_data(period="yearly")

Which returns:

get_intraday_data

Returns intraday historical data for the specified tickers. This contains the following columns: - Open: The opening price for the period. - High: The highest price for the period. - Low: The lowest price for the period. - Close: The closing price for the period. - Volume: The volume for the period. - Return: The return for the period. - Cumulative Return: The cumulative return for the period.

Volatility is not included here. This is available as a dedicated calculation in the Risk module instead (e.g. toolkit.risk.get_volatility).

Keep in mind that this data is available for a shorter period. This means that the start date is ignored if the difference between the start and end date is bigger than the maximum period.

If a benchmark ticker is selected, it also calculates the benchmark ticker together with the results. By default this is set to “SPY” (S&P 500 Index) but can be any ticker. This is relevant for calculations for models such as CAPM, Alpha and Beta.

Please note that this functionality is only available through Financial Modeling Prep. Therefore, an api_key is required to use this functionality.

Also known as: tick data, minute data, intraday price history.

Args:

• period (str, optional): The intraday interval to fetch (e.g. “1min”, “5min”, “1hour”). Defaults to “1hour”.
• return_column (str, optional): The column to use for the return calculation. Defaults to “Close”.
• fill_nan (bool, optional): Defines whether to forward fill NaN values. Defaults to True.
• rounding (int \| None, optional): Defines the number of decimal places to round the data to. Defaults to None.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pandas.DataFrame: The intraday data for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit("MSFT", api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.get_intraday_data(period="1min")

Which returns:

get_dividend_calendar

Obtain Dividend Calendars for any range of companies. It includes the following columns: - Date: The date of the dividend. - Adj Dividend: The adjusted dividend amount. - Dividend: The dividend amount. - Record Date: The record date of the dividend. - Payment Date: The payment date of the dividend. - Declaration Date: The declaration date of the dividend.

If a company does not pay any dividend, the function will mention that it was not able to find any dividend data for that company.

Also known as: dividend dates, ex-dividend date, dividend history.

Args:

• overwrite (bool): Defines whether to overwrite the existing data.
• rounding (int): Defines the number of decimal places to round the data to.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pd.DataFrame: The earnings calendar for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(
    ["AAPL", "MSFT", "GOOGL", "AMZN"], api_key="FINANCIAL_MODELING_PREP_KEY", start_date="2022-08-01", quarterly=False
)

dividend_calendar = toolkit.get_dividend_calendar()

dividend_calendar.loc['AAPL']

Which returns:

get_esg_scores

ESG scores, which stands for Environmental, Social, and Governance scores, are a crucial metric used by investors and organizations to assess a company’s sustainability and ethical practices. These scores provide valuable insights into a company’s performance in three key areas:

• Environmental (E): The environmental component evaluates a company’s impact on the planet and its efforts to mitigate environmental risks. It includes factors like carbon emissions, energy efficiency, water management, and waste reduction. A high environmental score indicates a company’s commitment to eco-friendly practices and reducing its ecological footprint.
• Social (S): The social component focuses on how a company interacts with its employees, customers, suppliers, and the communities in which it operates. Key factors in the social score include labor practices, diversity and inclusion, human rights, product safety, and community engagement. A strong social score reflects a company’s dedication to fostering positive relationships and contributing positively to society.
• Governance (G): Governance examines a company’s internal structures, policies, and leadership. It assesses aspects such as board independence, executive compensation, transparency, and the presence of anti-corruption measures. A high governance score signifies strong leadership and a commitment to maintaining high ethical standards and accountability

ESG scores provide investors with a holistic view of a company’s sustainability and ethical practices, allowing them to make more informed investment decisions. These scores are increasingly used to identify socially responsible investments and guide capital towards companies that prioritize long-term sustainability and responsible business practices. As the importance of ESG considerations continues to grow, companies are motivated to improve their ESG scores, not only for ethical reasons but also to attract investors who value sustainable and responsible business practices.

Also known as: environmental social governance, sustainability, ESG rating.

Args:

• overwrite (bool): Defines whether to overwrite the existing data.
• rounding (int): Defines the number of decimal places to round the data to.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pd.DataFrame: The ESG scores for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(
    ["MSFT", "TSLA", "AMZN"], api_key="FINANCIAL_MODELING_PREP_KEY", start_date="2022-08-01", quarterly=False
)

esg_scores = toolkit.get_esg_scores()

esg_scores.xs("MSFT", level=1, axis=1)

Which returns:

get_market_risk_premium

Obtains the equity market risk premium by country – the country default spread plus the equity risk premium, following the approach popularized by Aswath Damodaran – which is widely used to calibrate country-specific costs of equity and discount rates in a multi-country setting.

Also known as: country risk premium, Damodaran equity risk premium.

Args:

• overwrite (bool): Defines whether to overwrite the existing data.

Raises:

ValueError: If an API key is not defined for FinancialModelingPrep.

Returns:

pd.DataFrame: The market risk premium by country, including the continent, Country Risk Premium and Total Equity Risk Premium (both in percentage points).

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AMZN", "TSLA"], api_key="FINANCIAL_MODELING_PREP_KEY")

market_risk_premium = toolkit.get_market_risk_premium()

market_risk_premium.loc[['United States', 'Germany', 'Brazil']]

Which returns:

get_commitment_of_traders

Obtains the CFTC Commitment of Traders (COT) report for the tickers the Toolkit was initialized with. Published weekly by the U.S. Commodity Futures Trading Commission, it breaks down open interest in futures markets by trader type – Non-Commercial (large speculators), Commercial (hedgers) and Non-Reportable (small traders) – and is widely used to gauge positioning and sentiment in commodity, currency, interest rate and stock index futures markets.

Note that this data is only available for CFTC-tracked futures markets. Tickers without a corresponding futures contract (e.g. most individual equities) return no data.

Also known as: COT report, CFTC positioning data, speculator/hedger positioning.

Args:

• overwrite (bool): Defines whether to overwrite the existing data.

Raises:

ValueError: If an API key is not defined for FinancialModelingPrep.

Returns:

pd.DataFrame: The Commitment of Traders report for the specified tickers.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["NG", "GC"], api_key="FINANCIAL_MODELING_PREP_KEY")

commitment_of_traders = toolkit.get_commitment_of_traders()

commitment_of_traders.xs("NG", level=1, axis=1)[
    ["Open Interest", "Non-Commercial Long", "Non-Commercial Short", "Commercial Long", "Commercial Short"]
].tail()

Which returns:

get_historical_statistics

Retrieve statistics about each ticker’s historical data. This is especially useful to understand why certain tickers might fluctuate more than others as it could be due to local regulations or the currency the instrument is denoted in. It returns:

• Currency: The currency the instrument is denoted in.
• Symbol: The symbol of the instrument.
• Exchange Name: The name of the exchange the instrument is listed on.
• Instrument Type: The type of instrument.
• First Trade Date: The date the instrument was first traded.
• Regular Market Time: The time the instrument is traded.
• GMT Offset: The GMT offset.
• Timezone: The timezone the instrument is traded in.
• Exchange Timezone Name: The name of the timezone the instrument is traded in.

Also known as: key statistics over time, historical key metrics.

Returns: pd.DataFrame: A DataFrame containing the statistics for each ticker.

from financetoolkit import Toolkit

companies = Toolkit(["AMZN", "^HSI", "IWDA.AS", "0P0000Z8RO.T"])

companies.get_historical_statistics()

Which returns:

get_treasury_data

Retrieve daily, weekly, monthly, quarterly or yearly treasury data. This can be from FinancialModelingPrep or from YahooFinance. FinancialModelingPrep is by far a more extensive dataset containing daily data from 1 month to 30 years. YahooFinance only contains daily data for 5, 10 and 30 years but is a free alternative.

Also known as: US Treasury yields, yield curve, treasury rates.

Args:

• period (str): The interval at which the treasury data should be returned - daily, weekly, monthly, quarterly, or yearly.
• fill_nan (bool): Defines whether to forward fill NaN values. This defaults to True to prevent holes in the dataset. This is especially relevant for technical indicators.
• risk_free_rate (str \| None, optional): The maturity to return as the risk free rate (‘13w’, ‘5y’, ‘10y’ or ‘30y’). Defaults to None, which uses the maturity set on the Toolkit.
• divide_ohlc_by (int \| float \| None, optional): A value to divide the yields by. Treasury yields are published in percent, so this defaults to 100 to return decimals.
• rounding (int \| None, optional): The number of decimals to round the results to. Defaults to None, which uses the rounding set on the Toolkit.
• show_errors (bool, optional): Whether to report retrieval errors. Defaults to False.
• enforce_source (str \| None, optional): Forces this specific call to use a given source, either “FinancialModelingPrep” or “YahooFinance”. This takes precedence over the source set on the Toolkit itself. Defaults to None, which falls back to the Toolkit’s own enforce_source.

Returns:

pd.DataFrame: A DataFrame containing the treasury data.

As an example:

from financetoolkit import Toolkit

companies = Toolkit(["AAPL", "MSFT"], api_key="FINANCIAL_MODELING_PREP_KEY", start_date="2023-08-10")

companies.get_treasury_data()

Which returns:

get_exchange_rates

This functionality looks at the exchange rates between the currency of the historical data and the currency of the financial statements. Given that these can deviate from each other, e.g. the historical data is in USD but the financial statements are in EUR, it is important to adjust for this. This is especially relevant for models that use the historical data and the financial statements.

This function therefore shows the exchange rates that are used to convert the financial statements to the currency of the historical data. The historical market data is quote currency and the financial statements are base currency.

Note that you can get currency data from any currency as well by supplying the currency as a ticker. For example, if you want to get the exchange rates between USD and EUR you can use USDEUR=X as a ticker.

Important to note is that when an api_key is included in the Toolkit initialization that the data collection defaults to FinancialModelingPrep which is a more stable source and utilises your subscription. However, if this is undesired, it can be disabled by setting enforce_source to “YahooFinance”. If data collection fails from FinancialModelingPrep it automatically reverts back to YahooFinance.

Also known as: currency exchange, FX rates, foreign exchange rates.

Args:

• period (str): The interval at which the historical data should be returned - daily, weekly, monthly, quarterly, or yearly. Defaults to “daily”.
• return_column (str): The column to use for the return calculation. Defaults to “Adj Close”.
• fill_nan (bool): Defines whether to forward fill NaN values. This defaults to True to prevent holes in the dataset. This is especially relevant for technical indicators.
• overwrite (bool): Defines whether to overwrite the existing data.
• rounding (int): Defines the number of decimal places to round the data to.
• show_ticker_seperation (bool, optional): A boolean representing whether to show which tickers acquired data from FinancialModelingPrep and which tickers acquired data from YahooFinance.

Raises:

ValueError: If an invalid value is specified for period.

Returns:

pandas.DataFrame: The historical exchange rate data.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit("ASML", api_key="FINANCIAL_MODELING_PREP_KEY")

toolkit.get_exchange_rates(period="monthly")

Which returns:

get_balance_sheet_statement

Retrieves the balance sheet statement data for the specified tickers. The balance sheet statement is a financial statement that provides a snapshot of a company’s financial position at a specific point in time. It shows the company’s assets, liabilities, and shareholders’ equity. The balance sheet statement is divided into three main sections:

• Assets: Assets are resources owned by the company that have economic value and can be used to generate revenue. Assets are typically divided into current assets and non-current assets.
• Liabilities: Liabilities are obligations that the company owes to external parties. Liabilities are also divided into current liabilities and non-current liabilities.
• Shareholders’ Equity: Shareholders’ equity represents the company’s net worth or book value. It is calculated as the difference between the company’s assets and liabilities.

Note that the balance sheet statement is a financial statement that provides a snapshot of a company’s financial position at a specific point in time. Therefore, trailing results are not available for this statement.

Also known as: assets, liabilities, shareholders equity, financial position.

Args:

• enforce_source (str \| None, optional): Forces this specific call to use a given source, either “FinancialModelingPrep” or “YahooFinance”. This takes precedence over the source set on the Toolkit itself, so one instance can pull historical data from the free Yahoo Finance source while still using a FinancialModelingPrep key for the financial statements (or the other way around). Defaults to None, which falls back to the Toolkit’s own enforce_source.
• overwrite (bool): Defines whether to overwrite the existing data.
• rounding (int): Defines the number of decimal places to round the data to.
• growth (bool): Defines whether to return the growth of the data.
• lag (int \| str): Defines the number of periods to lag the growth data by. E.g. when selecting 4 with quarterly data, the TTM is calculated.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pd.DataFrame: A pandas DataFrame with the retrieved balance sheet statement data.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["MSFT", "MU"], api_key="FINANCIAL_MODELING_PREP_KEY", quarterly=True, start_date='2022-05-01')

balance_sheet_statements = toolkit.get_balance_sheet_statement()

balance_sheet_statements.loc['MU']

Which returns:

get_income_statement

Retrieves the income statement data for the specified tickers. The income statement is a financial statement that shows a company’s revenues and expenses over a specific period. It is used to calculate a company’s net income.

The income statement is a financial statement that shows a company’s revenues and expenses over a specific period. Therefore, trailing results are available for this statement.

Also known as: profit and loss, revenue, net income, earnings, P&L statement.

Args:

• enforce_source (str \| None, optional): Forces this specific call to use a given source, either “FinancialModelingPrep” or “YahooFinance”. This takes precedence over the source set on the Toolkit itself, so one instance can pull historical data from the free Yahoo Finance source while still using a FinancialModelingPrep key for the financial statements (or the other way around). Defaults to None, which falls back to the Toolkit’s own enforce_source.
• overwrite (bool): Defines whether to overwrite the existing data.
• rounding (int): Defines the number of decimal places to round the data to.
• growth (bool): Defines whether to return the growth of the data.
• lag (int \| str): Defines the number of periods to lag the growth data by.
• trailing (int): Defines whether to select a trailing period. E.g. when selecting 4 with quarterly data, the TTM is calculated.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pd.DataFrame: A pandas DataFrame with the retrieved income statement data.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["TSLA", "MU"], api_key="FINANCIAL_MODELING_PREP_KEY", quarterly=True, start_date='2022-05-01')

income_sheet_statements = toolkit.get_income_statement()

income_sheet_statements.loc['TSLA']

Which returns:

get_cash_flow_statement

Retrieves the cash flow statement data for the specified tickers. The cash flow statement is a financial statement that shows how changes in balance sheet accounts and income affect cash and cash equivalents. It breaks the analysis down to operating, investing and financing activities.

The cash flow statement is a financial statement that shows how changes in balance sheet accounts and income affect cash and cash equivalents. Therefore, trailing results are available for this statement.

Also known as: operating cash flow, investing activities, financing activities.

Args:

• enforce_source (str \| None, optional): Forces this specific call to use a given source, either “FinancialModelingPrep” or “YahooFinance”. This takes precedence over the source set on the Toolkit itself, so one instance can pull historical data from the free Yahoo Finance source while still using a FinancialModelingPrep key for the financial statements (or the other way around). Defaults to None, which falls back to the Toolkit’s own enforce_source.
• overwrite (bool): Defines whether to overwrite the existing data.
• rounding (int): Defines the number of decimal places to round the data to.
• growth (bool): Defines whether to return the growth of the data.
• lag (int \| str): Defines the number of periods to lag the growth data by.
• trailing (int): Defines whether to select a trailing period. E.g. when selecting 4 with quarterly data, the TTM is calculated.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pd.DataFrame: A pandas DataFrame with the retrieved cash flow statement data.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["MU", "AMZN"], api_key="FINANCIAL_MODELING_PREP_KEY", quarterly=True, start_date='2022-09-01')

cash_flow_statements = toolkit.get_cash_flow_statement()

cash_flow_statements.loc['AMZN']

Which returns:

get_statistics_statement

Retrieves the balance, cash and income statistics for the company(s) from the specified source.

Note that this also obtains the balance sheet statement at the same time given that it’s the same API call. This is done to reduce the number of API calls to FinancialModelingPrep.

Also known as: key stats, shares outstanding, float data.

Args:

• enforce_source (str \| None, optional): Forces this specific call to use a given source, either “FinancialModelingPrep” or “YahooFinance”. This takes precedence over the source set on the Toolkit itself, so one instance can pull historical data from the free Yahoo Finance source while still using a FinancialModelingPrep key for the financial statements (or the other way around). Defaults to None, which falls back to the Toolkit’s own enforce_source.
• overwrite (bool): Defines whether to overwrite the existing data.
• rounding (int): Defines the number of decimal places to round the data to.
• show_columns (list[str] \| None): A list of column names to keep in the result. Invalid names are reported and ignored. Defaults to None, which keeps every column.

Returns:

pd.DataFrame: A pandas DataFrame with the retrieved statistics statement data.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit("TSLA", api_key="FINANCIAL_MODELING_PREP_KEY", quarterly=True, start_date='2023-05-01')

toolkit.get_statistics_statement()

Which returns:

get_normalization_files

Copies the normalization files to a folder based on path. By default, this is the path of the ‘Downloads’ folder.

This function is relevant if you want to supply your own datasets. See for a proper guide the following notebook: https://www.jeroenbouma.com/projects/financetoolkit/external-datasets

Args:

• path (str, optional): The path where to save the files to.

Returns:

Three csv files saved to the desired location.

get_cache_contents

Show what the cache currently holds, grouped by source and dataset.

The cache stores data per source, per dataset and per entity (a ticker, a country, a series identifier), which makes it possible to remove part of it rather than all of it. This method is the counterpart to clear_cache: it shows what is there so that removing something is an informed decision.

The cache is inspected regardless of whether this Toolkit was created with use_cached_data enabled, so a cache filled by an earlier session can always be reviewed.

Returns: pd.DataFrame: One row per source and dataset combination, with the number of entities, the number of stored entries and when they were written. An empty DataFrame when the cache holds nothing.

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "MSFT"], api_key="FINANCIAL_MODELING_PREP_KEY", use_cached_data=True)

toolkit.get_historical_data()

toolkit.get_cache_contents()

Which returns:

clear_cache

Remove cached data, either all of it or only the part you specify.

The Finance Toolkit never clears the cache on its own. A cache can represent a large amount of downloaded data and a meaningful part of an API quota, so discarding it is always an explicit action. Even a change in the cache’s own internal structure only produces a warning pointing at this method rather than removing anything.

Because the cache is stored per source, per dataset and per entity, removal can be narrowed instead of wholesale. Clearing a single stale ticker, or everything retrieved from one provider, leaves the rest of the cache intact.

Args:

• source (str \| None): Only remove data from this source, for example “FinancialModelingPrep”, “YahooFinance”, “OECD”, “FRED” or “GlobalMacroDatabase”. These match the names used by enforce_source. Defaults to None, which matches every source.
• dataset (str \| None): Only remove this dataset within the source, for example “historical”, “intraday” or “statements”. Defaults to None, which matches every dataset.
• ticker (str \| None): Only remove this entity, for example “AAPL” or a country code for macroeconomic data. Defaults to None, which matches every entity.
• confirm (bool): Required to be True when no source, dataset or ticker is given, since that removes the entire cache. Defaults to False.

Raises:

ValueError: If the whole cache would be removed without confirm being set.

Returns:

int: The number of stored entries that were removed.

As an example:

from financetoolkit import Toolkit

toolkit = Toolkit(["AAPL", "MSFT"], api_key="FINANCIAL_MODELING_PREP_KEY", use_cached_data=True)

# Remove only the price history of a single ticker
toolkit.clear_cache(source="YahooFinance", ticker="AAPL")

# Remove everything retrieved from the OECD
toolkit.clear_cache(source=policy_model.OECD)

# Remove the entire cache
toolkit.clear_cache(confirm=True)