fmp_py.fmp_earnings

Classes

FmpEarnings

Module Contents

class fmp_py.fmp_earnings.FmpEarnings(api_key: str = os.getenv('FMP_API_KEY'))

Bases: fmp_py.fmp_base.FmpBase

earnings_surprises(symbol: str) → pandas.DataFrame

Retrieves the earnings surprises for a given symbol. :param symbol: The symbol of the stock. :type symbol: str

Returns:

A DataFrame containing the earnings surprises data.

Return type:

pd.DataFrame

earnings_confirmed(from_date: str, to_date: str) → pandas.DataFrame

Fetches the confirmed earnings calendar data from the specified date range. :param from_date: The starting date of the range in the format ‘YYYY-MM-DD’. :type from_date: str :param to_date: The ending date of the range in the format ‘YYYY-MM-DD’. :type to_date: str

Returns:

A DataFrame containing the fetched earnings calendar data, with the following columns:

  • symbol: The symbol of the company.

  • exchange: The exchange where the company is listed.

  • time: The time of the earnings release.

  • when: The time period of the earnings release (e.g., ‘Before Market Open’, ‘After Market Close’).

  • date: The date of the earnings release.

  • publication_date: The publication date of the earnings release.

  • title: The title of the earnings release.

  • url: The URL of the earnings release.

Return type:

pd.DataFrame

Raises:

ValueError – If there is an error fetching the earnings calendar data.

earnings_calendar(from_date: str, to_date: str) → pandas.DataFrame

Retrieves the earnings calendar data from the specified date range. :param from_date: The starting date of the earnings calendar data in “YYYY-MM-DD” format. :type from_date: str :param to_date: The ending date of the earnings calendar data in “YYYY-MM-DD” format. :type to_date: str

Returns:

A DataFrame containing the earnings calendar data with the following columns:

  • date: The date of the earnings release.

  • symbol: The symbol of the company.

  • eps: The earnings per share.

  • eps_estimated: The estimated earnings per share.

  • time: The time of the earnings release.

  • revenue: The revenue.

  • revenue_estimated: The estimated revenue.

  • fiscal_date_ending: The fiscal date ending.

  • updated_from_date: The updated from date.

Return type:

pd.DataFrame

Raises:

ValueError – If from_date is greater than to_date or if there is an error fetching the earnings calendar data.

earnings_historical(symbol: str) → pandas.DataFrame

Fetches historical earnings data for a given symbol. :param symbol: The symbol for which to fetch earnings data. :type symbol: str

Returns:

A DataFrame containing the historical earnings data, with the following columns:

  • date (datetime64[ns]): The date of the earnings release.

  • symbol (str): The symbol of the company.

  • eps (float): The earnings per share.

  • revenue (int): The revenue.

  • eps_estimated (float): The estimated earnings per share.

  • revenue_estimated (int): The estimated revenue.

  • time (str): The time of the earnings release.

  • updated_from_date (datetime64[ns]): The date from which the data was last updated.

  • fiscal_date_ending (datetime64[ns]): The fiscal date ending.

Return type:

pd.DataFrame

Raises:

ValueError – If there is an error fetching the earnings historical data.

earnings_within_weeks(symbol: str, weeks_ahead: int = 2) → bool

Checks if there are earnings within a specified number of weeks ahead. :param symbol: The symbol of the stock. :type symbol: str :param weeks_ahead: The number of weeks ahead to check for earnings. Defaults to 2. :type weeks_ahead: int, optional

Returns:

True if there are earnings within the specified number of weeks ahead, False otherwise.

Return type:

bool