Discovery

The Discovery Module contains lists of companies, cryptocurrencies, forex, commodities, ETFs and indices including screeners, quotes, performance metrics and more to find and select tickers to use in the Finance Toolkit.

To install the FinanceToolkit it simply requires the following:

pip install financetoolkit -U

search_instruments

The search instruments function allows you to search for a company or financial instrument by name. It returns a dataframe with all the symbols that match the query.

Also known as: find companies, lookup stocks, ticker search, instrument search.

Args:

• query (str): A query to search for, e.g. ‘META’.
• search_method (str, optional): The field to search against. Valid options are ‘symbol’, ‘name’, ‘cik’, ‘cusip’, and ‘isin’. Defaults to ‘name’.

Returns:

pd.DataFrame: A dataframe with all the symbols that match the query.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

discovery.search_instruments(query='META')

Which returns:

get_stock_screener

Screen stocks based on a set of criteria. This can be useful to find companies that match a specific criteria or your analysis. Further filtering can be done by utilising the Finance Toolkit and calculating the relevant ratios to filter by. This can be:

• Market capitalization (market_cap_higher, market_cap_lower)
• Price (price_higher, price_lower)
• Beta (beta_higher, beta_lower)
• Volume (volume_higher, volume_lower)
• Dividend (dividend_higher, dividend_lower)
• Classification (sector, industry, country, exchange, is_etf)

The result is capped at limit companies, 1000 by default. Getting back exactly that many means the list was truncated, which is warned about in the log; narrow the criteria or raise the limit to see the remainder.

Also known as: filter stocks, financial criteria screener.

Args:

• market_cap_higher (int): The minimum market capitalization of the stock, in the currency of the listing rather than in millions.
• market_cap_lower (int): The maximum market capitalization of the stock.
• price_higher (int): The minimum price of the stock.
• price_lower (int): The maximum price of the stock.
• beta_higher (int): The minimum beta of the stock.
• beta_lower (int): The maximum beta of the stock.
• volume_higher (int): The minimum volume of the stock, in shares traded.
• volume_lower (int): The maximum volume of the stock.
• dividend_higher (int): The minimum dividend of the stock, as an amount per share over the last annual period rather than as a yield.
• dividend_lower (int): The maximum dividend of the stock.
• sector (str \| None): The sector to restrict the screen to, e.g. “Energy”.
• industry (str \| None): The industry to restrict the screen to, e.g. “Biotechnology”.
• country (str \| None): The two-letter country code to restrict the screen to, e.g. “US”.
• exchange (str \| None): The exchange code to restrict the screen to, e.g. “NASDAQ”.
• is_etf (bool \| None): Whether to restrict the screen to ETFs or to exclude them.
• limit (int): The maximum number of companies to return. Defaults to 1000.

Returns:

pd.DataFrame: A dataframe with all the symbols that match the query. An empty dataframe is returned when nothing matches.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

discovery.get_stock_screener(
    market_cap_higher=1000000,
    market_cap_lower=200000000000,
    price_higher=100,
    price_lower=200,
    beta_higher=1,
    beta_lower=1.5,
    volume_higher=100000,
    volume_lower=2000000,
    dividend_higher=1,
    dividend_lower=2,
    is_etf=False
)

Which returns:

get_stock_list

The stock list function returns a complete list of all the symbols that can be used in the Finance Toolkit. These are over 60.000 symbols.

Returns: pd.DataFrame: A dataframe with all the symbols in the toolkit.

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

stock_list = discovery.get_stock_list()

# The total list equals over 60.000 rows
stock_list.iloc[38000:38010]

Which returns:

get_stock_shares_float

Returns the shares float for each company. The shares float is the number of shares available for trading for each company. It also includes the number of shares outstanding and the date.

Returns: pd.DataFrame: A dataframe with the shares float for each company.

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

shares_float = discovery.get_stock_shares_float()

shares_float.iloc[50000:50010]

Which returns:

get_sectors_performance

Returns the historical performance of every sector, one column per sector.

The values are the average percentage change of the companies in that sector on that date, so 1.25 means +1.25% and not +125%. One API call is made per sector because the combined endpoint this used to read was retired and now answers with an empty response.

Without a date range the API hands back only the earliest days it holds, so pass start_date and end_date to look at a recent window.

Args:

• start_date (str \| None): The start date to filter data with, e.g. “2024-01-01”.
• end_date (str \| None): The end date to filter data with, e.g. “2024-12-31”.

Returns:

pd.DataFrame: A dataframe with the sectors performance for each sector.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

sectors_performance = discovery.get_sectors_performance()

sectors_performance.tail()

Which returns:

get_biggest_gainers

Returns the biggest gainers for the day. This includes the symbol, the name, the price, the change and the change percentage.

Returns: pd.DataFrame: A dataframe with the biggest gainers for the day.

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

biggest_gainers = discovery.get_biggest_gainers()

biggest_gainers.head(10)

Which returns:

get_biggest_losers

Returns the biggest losers for the day. This includes the symbol, the name, the price, the change and the change percentage.

Returns: pd.DataFrame: A dataframe with the biggest losers for the day.

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

biggest_losers = discovery.get_biggest_losers()

biggest_losers.head(10)

Which returns:

get_most_active_stocks

Returns the most active stocks for the day. This includes the symbol, the name, the price, the change and the change percentage.

Returns: pd.DataFrame: A dataframe with the most active stocks for the day.

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

most_active_stocks = discovery.get_most_active_stocks()

most_active_stocks.head(10)

Which returns:

get_delisted_stocks

The delisted stocks function returns a page of delisted stocks including the IPO and delisted date.

The endpoint hands out at most 100 rows per call, so this is one page of the list rather than the whole of it. Walk page upwards until an empty frame comes back to collect everything.

Args:

• page (int): The page of results to retrieve, starting at 0. Defaults to 0.
• limit (int): The number of results per page, capped at 100 by the API. Defaults to 100.

Returns:

pd.DataFrame: A dataframe with one page of delisted stocks.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

delisted_stocks = discovery.get_delisted_stocks()

delisted_stocks.head(10)

Which returns:

get_crypto_list

The crypto list function returns a complete list of all crypto symbols that can be used in the Finance Toolkit. These are over 4.000 symbols.

Returns: pd.DataFrame: A dataframe with all the symbols in the toolkit.

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

crypto_list = discovery.get_crypto_list()

crypto_list.head(10)

Which returns:

get_forex_list

The forex list function returns a complete list of all forex symbols that can be used in the Finance Toolkit. These are over 1.000 symbols.

Returns: pd.DataFrame: A dataframe with the forex symbols.

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

forex_list = discovery.get_forex_list()

forex_list.head(10)

Which returns:

get_commodity_list

The commodity list function returns a complete list of all commodity symbols that can be used in the Finance Toolkit.

Returns: pd.DataFrame: A dataframe with all the commodities available.

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

commodity_list = discovery.get_commodity_list()

commodity_list.head(10)

Which returns:

get_etf_list

The etf list function returns a complete list of all etf symbols that can be used in the Finance Toolkit.

Returns: pd.DataFrame: A dataframe with all the etf symbols.

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

etf_list = discovery.get_etf_list()

etf_list.head(10)

Which returns:

get_index_list

The index list function returns a complete list of all etf symbols that can be used in the Finance Toolkit.

Returns: pd.DataFrame: A dataframe with all the index symbols.

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

index_list = discovery.get_index_list()

index_list.head(10)

Which returns:

get_stock_news

Returns the latest stock market news articles. This includes the ticker symbol (when applicable), publisher, title, a short snippet, and the article URL.

Also known as: stock news feed, market news headlines.

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.
• start_date (str, optional): The start date to filter data with.
• end_date (str, optional): The end date to filter data with.

Returns:

pd.DataFrame: A dataframe with the latest stock market news articles.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

stock_news = discovery.get_stock_news(limit=5)

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

Which returns:

get_general_news

Returns the latest general news articles, spanning macroeconomic and broad market coverage rather than a specific ticker.

Also known as: general market news, macro 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.

Returns:

pd.DataFrame: A dataframe with the latest general news articles.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

general_news = discovery.get_general_news(limit=5)

general_news[["Publisher", "Title"]]

Which returns:

get_press_releases

Returns the latest official company press releases, such as earnings announcements, mergers, and other corporate communications.

Also known as: corporate announcements, company press releases.

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.
• start_date (str, optional): The start date to filter data with.
• end_date (str, optional): The end date to filter data with.

Returns:

pd.DataFrame: A dataframe with the latest company press releases.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

press_releases = discovery.get_press_releases(limit=5)

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

Which returns:

get_crypto_news

Returns the latest cryptocurrency news articles.

Also known as: crypto news feed, digital asset news.

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.

Returns:

pd.DataFrame: A dataframe with the latest cryptocurrency news articles.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

crypto_news = discovery.get_crypto_news(limit=5)

crypto_news[["Symbol", "Publisher", "Title"]]

Which returns:

get_forex_news

Returns the latest forex news articles.

Also known as: forex news feed, currency market news.

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.

Returns:

pd.DataFrame: A dataframe with the latest forex news articles.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

forex_news = discovery.get_forex_news(limit=5)

forex_news[["Symbol", "Publisher", "Title"]]

Which returns:

search_stock_news

Searches stock market news articles by one or more ticker symbols.

Also known as: ticker news search, company news lookup.

Args:

• symbols (str \| list[str]): One or more ticker symbols, e.g. “AAPL” or [“AAPL”, “MSFT”].
• 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.
• start_date (str, optional): The start date to filter data with.
• end_date (str, optional): The end date to filter data with.

Returns:

pd.DataFrame: A dataframe with stock news articles matching the given symbols.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

stock_news = discovery.search_stock_news(symbols="AAPL", limit=5)

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

Which returns:

search_press_releases

Searches company press releases by one or more ticker symbols.

Also known as: press release search, corporate announcement lookup.

Args:

• symbols (str \| list[str]): One or more ticker symbols, e.g. “AAPL” or [“AAPL”, “MSFT”].
• 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.
• start_date (str, optional): The start date to filter data with.
• end_date (str, optional): The end date to filter data with.

Returns:

pd.DataFrame: A dataframe with press releases matching the given symbols.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

press_releases = discovery.search_press_releases(symbols="AAPL", limit=5)

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

Which returns:

search_crypto_news

Searches cryptocurrency news articles by one or more coin/token symbols.

Also known as: crypto news search, coin news lookup.

Args:

• symbols (str \| list[str]): One or more crypto symbols, e.g. “BTCUSD” or [“BTCUSD”, “ETHUSD”].
• 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.

Returns:

pd.DataFrame: A dataframe with crypto news articles matching the given symbols.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

crypto_news = discovery.search_crypto_news(symbols="BTCUSD", limit=5)

crypto_news[["Symbol", "Publisher", "Title"]]

Which returns:

search_forex_news

Searches forex news articles by one or more currency pair symbols.

Also known as: forex news search, currency pair news lookup.

Args:

• symbols (str \| list[str]): One or more forex pairs, e.g. “EURUSD” or [“EURUSD”, “GBPUSD”].
• 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.

Returns:

pd.DataFrame: A dataframe with forex news articles matching the given symbols.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

forex_news = discovery.search_forex_news(symbols="EURUSD", limit=5)

forex_news[["Symbol", "Publisher", "Title"]]

Which returns:

get_ipo_calendar

Returns the calendar of upcoming and recent initial public offerings (IPOs), including expected pricing, exchange, and share count. This is distinct from the “IPO Date” field on a company’s profile, which only shows a single past date.

Note that the date range is limited to a maximum of 90 days.

Also known as: IPO pipeline, upcoming listings.

Args:

• start_date (str, optional): The start date to filter data with.
• end_date (str, optional): The end date to filter data with.

Returns:

pd.DataFrame: A dataframe with upcoming and recent IPOs.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

ipo_calendar = discovery.get_ipo_calendar(start_date="2024-01-01", end_date="2024-06-01")

ipo_calendar.head()

Which returns:

get_ipo_disclosures

Returns IPO disclosure filings - the regulatory filings made ahead of an IPO, including filing dates, effectiveness dates, and CIK numbers, with direct links to the official SEC documents.

Also known as: pre-IPO SEC filings, IPO regulatory disclosures.

Args:

• start_date (str, optional): The start date to filter data with.
• end_date (str, optional): The end date to filter data with.

Returns:

pd.DataFrame: A dataframe with IPO disclosure filings.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

ipo_disclosures = discovery.get_ipo_disclosures(start_date="2024-01-01", end_date="2024-06-01")

ipo_disclosures.head()

Which returns:

get_ipo_prospectuses

Returns IPO prospectus filings, including public offering price, discounts and commissions, and proceeds before expenses, with links to the official SEC prospectus documents.

Also known as: IPO pricing details, S-1/424B4 filings.

Args:

• start_date (str, optional): The start date to filter data with.
• end_date (str, optional): The end date to filter data with.

Returns:

pd.DataFrame: A dataframe with IPO prospectus filings.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

ipo_prospectuses = discovery.get_ipo_prospectuses(start_date="2024-01-01", end_date="2024-06-01")

ipo_prospectuses.head()

Which returns:

get_stock_splits_calendar

Returns the calendar of upcoming and recent stock splits across all companies, including the split date and ratio. Same calendar pattern as the earnings and dividend calendars.

Note that the date range is limited to a maximum of 90 days.

Also known as: split schedule, upcoming stock splits.

Args:

• start_date (str, optional): The start date to filter data with.
• end_date (str, optional): The end date to filter data with.

Returns:

pd.DataFrame: A dataframe with upcoming and recent stock splits.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

splits_calendar = discovery.get_stock_splits_calendar(start_date="2024-01-01", end_date="2024-06-01")

splits_calendar.head()

Which returns:

get_sector_performance

Returns sector performance - the average price change per sector. Provide exactly one of date (a snapshot across all sectors on that date) or sector (the historical time series for one sector).

Also known as: sector performance snapshot, sector performance history, sector trend.

Args:

• date (str, optional): The date to retrieve a snapshot for, e.g. “2024-02-01”.
• sector (str, optional): The sector to retrieve the history for, e.g. “Energy”.

Returns:

pd.DataFrame: A dataframe with sector performance, indexed by Sector (snapshot) or Date (historical).

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

sector_snapshot = discovery.get_sector_performance(date="2024-02-01")

sector_snapshot.head()

sector_history = discovery.get_sector_performance(sector="Energy")

sector_history.tail()

Which returns:

get_industry_performance

Returns industry performance - the average price change per industry. Provide exactly one of date (a snapshot across all industries on that date) or industry (the historical time series for one industry).

Also known as: industry performance snapshot, industry performance history, industry trend.

Args:

• date (str, optional): The date to retrieve a snapshot for, e.g. “2024-02-01”.
• industry (str, optional): The industry to retrieve the history for, e.g. “Biotechnology”.

Returns:

pd.DataFrame: A dataframe with industry performance, indexed by Industry (snapshot) or Date (historical).

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

industry_snapshot = discovery.get_industry_performance(date="2024-02-01")

industry_snapshot.head()

industry_history = discovery.get_industry_performance(industry="Biotechnology")

industry_history.tail()

Which returns:

get_sector_pe

Returns sector price-to-earnings (P/E) ratios. Provide exactly one of date (a snapshot across all sectors on that date) or sector (the historical time series for one sector).

Also known as: sector P/E snapshot, sector P/E history, sector valuation trend.

Args:

• date (str, optional): The date to retrieve a snapshot for, e.g. “2024-02-01”.
• sector (str, optional): The sector to retrieve the history for, e.g. “Energy”.

Returns:

pd.DataFrame: A dataframe with sector P/E ratios, indexed by Sector (snapshot) or Date (historical).

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

sector_pe = discovery.get_sector_pe(date="2024-02-01")

sector_pe.head()

sector_pe_history = discovery.get_sector_pe(sector="Energy")

sector_pe_history.tail()

Which returns:

get_industry_pe

Returns industry price-to-earnings (P/E) ratios. Provide exactly one of date (a snapshot across all industries on that date) or industry (the historical time series for one industry).

Also known as: industry P/E snapshot, industry P/E history, industry valuation trend.

Args:

• date (str, optional): The date to retrieve a snapshot for, e.g. “2024-02-01”.
• industry (str, optional): The industry to retrieve the history for, e.g. “Biotechnology”.

Returns:

pd.DataFrame: A dataframe with industry P/E ratios, indexed by Industry (snapshot) or Date (historical).

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

industry_pe = discovery.get_industry_pe(date="2024-02-01")

industry_pe.head()

industry_pe_history = discovery.get_industry_pe(industry="Biotechnology")

industry_pe_history.tail()

Which returns:

get_mergers_acquisitions_latest

Returns the most recent mergers and acquisitions deal announcements, including the acquirer and target companies and a link to the underlying SEC filing.

Also known as: M&A feed, deal announcements.

Args:

• limit (int, optional): The number of results to return. Defaults to 100.
• page (int, optional): The page number to retrieve. Defaults to 0.

Returns:

pd.DataFrame: A dataframe with the latest mergers and acquisitions.

As an example:

from financetoolkit import Discovery

discovery = Discovery(api_key="FINANCIAL_MODELING_PREP_KEY")

mergers_acquisitions = discovery.get_mergers_acquisitions_latest(limit=5)

mergers_acquisitions[["Company Name", "Targeted Company Name", "Transaction Date"]]

Which returns: