book
Checkout our new book! Hands on AI Trading with Python, QuantConnect, and AWS Learn More arrow

EOD Historical Data

Upcoming Earnings

Introduction

The Upcoming Earnings dataset, provided by EOD Historical Data (EODHD), is a daily universe of US Equities with an earnings report publication in the upcoming 7 days. The data starts in January 1998 and is delivered on a daily frequency.

Compared to Nasdaq's Earning Reports as a benchmark, the Upcoming Earnings dataset has captured 96.79% of the scheduled earnings report, with a 97.25% exact-date precision of the captured events, while having a 99.28% precision within +/- 3 days. Note that the Upcoming Earnings dataset also contains unscheduled special earning reports.

For more information about the Upcoming Earnings dataset, including CLI commands and pricing, see the dataset listing.

About the Provider

EOD Historical Data (EODHD) is a financial data provider based in France, and founded in April 2015. They focus on providing clean financial data, including stock prices, splits, dividends, fundamentals, macroeconomic indicators, technical indicators, and alternative data sources, through 24/7 API seamlessly. For more information about EODHD, visit https://eodhd.com/.

Getting Started

The following snippet demonstrates how to request data from the Upcoming Earnings dataset:

Select Language: 
self.add_universe(EODHDUpcomingEarnings, self.selection_function)

Data Summary

The following table describes the dataset properties:

PropertyValue
Start DateJanuary 1998
Data DensitySparse
ResolutionDaily
TimezoneNew York

Example Applications

The Upcoming Earnings dataset provides timely notifications about earnings announcements, allowing traders to make capitalize on potential price movements and manage risks effectively. Examples include the following strategies:

  • Short Straddle to trade on heightened volatility during earnings report.
  • Filter universe for the stocks with or without upcoming earnings report to trade or avoid volatility.
  • Hold the stocks with upcoming earnings estimated to be positive.

Data Point Attributes

The EODHD Upcoming Earnings dataset provides EODHDUpcomingEarnings objects, which have the following attributes:

EODHDUpcomingEarnings Select Language:
    The predetermined earnings report date.
  • report_date: DateTime
    • Whether the earnings report will be published before market open or after market closed on the report date.
  • report_time: ReportTime
    • The estimated earnings per share.
  • estimate: decimal
    • Time the data became available
  • end_time: DateTime
    • Market Data Type of this data - does it come in individual price packets or is it grouped into OHLC.
  • data_type: MarketDataType
    • True if this is a fill forward piece of data
  • is_fill_forward: bool
    • Current time marker of this data packet.
  • time: DateTime
    • Symbol representation for underlying Security
  • symbol: Symbol
    • Value representation of this data packet. All data requires a representative value for this moment in time. For streams of data this is the price now, for OHLC packets this is the closing price.
  • value: decimal
    • As this is a backtesting platform we'll provide an alias of value as price.
  • price: decimal

To filter the EODHD Upcoming Earnings data with their reporting timing, use the EODHD.ReportTime enum, which have the following attributes:

ReportTime Select Language:
    The earnings will be reported that day before market open.
  • BEFORE_MARKET: ReportTime
    • The earnings will be reported that day after market closed.
  • AFTER_MARKET: ReportTime

Universe Selection

To select a dynamic universe of US Equities based on the Upcoming Earnings dataset, call the add_universe method with a EODHDUpcomingEarnings cast.

Select Language: 
def initialize(self) -> None:
    self._universe = self.add_universe(EODHDUpcomingEarnings, self.universe_selection_filter)

def universe_selection_filter(self, earnings: List[EODHDUpcomingEarnings]) -> List[Symbol]:
    return [d.symbol for d in earnings if d.report_date <= self.time + timedelta(3) and d.estimate > 0]

For more information about universe settings, see Settings.

Requesting Data

This dataset is designed for universe selection. However, you can add Upcoming Earnings data to your algorithm using the add_data method.

Select Language: 
class UpcomingEarningsDataAlgorithm(QCAlgorithm):
    def initialize(self) -> None:
        self.set_start_date(2019, 1, 1)
        self.set_end_date(2020, 6, 1)
        self.set_cash(100000)

        self._symbol = self.add_equity("AAPL", Resolution.DAILY).symbol
        self._dataset_symbol = self.add_data(EODHDUpcomingEarnings, "earnings").symbol

Accessing Data

To get the current Upcoming Earnings data, call the get(EODHDUpcomingEarnings) method from the current Slice and index the result with the security Symbol. Slice objects deliver unique events to your algorithm as they happen, but the Slice may not contain data for your security at every time step. To avoid issues, check if the Slice contains the data you want before you index it.

Select Language: 
def on_data(self, slice: Slice) -> None:
    upcomings_earnings_for_symbol = slice.get(EODHDUpcomingEarnings).get(self._symbol)
        if upcomings_earnings_for_symbol:
            self.log(f"{self._symbol} will report earnings at {upcomings_earnings_for_symbol.report_date} {upcomings_earnings_for_symbol.report_time} with estimated EPS {upcomings_earnings_for_symbol.estimate}")

You can also iterate through all of the dataset objects in the current Slice

Select Language: 
def on_data(self, slice: Slice) -> None:
    for equity_symbol, upcomings_earnings_data_point in slice.get(EODHDUpcomingEarnings).items():
        self.log(f"{equity_symbol} will report earnings at {upcomings_earnings_data_point.report_date} {upcomings_earnings_data_point.report_time} with estimated EPS {upcomings_earnings_data_point.estimate}")

Historical Data

To get historical Upcoming Earnings for the universe, call the history method with the type EODHDUpcomingEarning.

Select Language: 
history = self.history(EODHDUpcomingEarnings, timedelta(100), Resolution.DAILY)

To get historical Upcoming Earnings data for a known security, call the history method with the type EODHDUpcomingEarning cast and the security Symbol.

Select Language: 
history = self.history[EODHDUpcomingEarnings](timedelta(100), Resolution.DAILY).loc[self._symbol]

If there is no data in the period you request, the history result is empty. For more information about historical data, see History Requests.

Remove Subscriptions

To remove a subscription, call the remove_security method.

Select Language: 
self.remove_security(self.dataset_symbol)

Example Applications

The Upcoming Earnings dataset provides timely notifications about earnings announcements, allowing traders to make capitalize on potential price movements and manage risks effectively. Examples include the following strategies:

  • Short Straddle to trade on heightened volatility during earnings report.
  • Filter universe for the stocks with or without upcoming earnings report to trade or avoid volatility.
  • Hold the stocks with upcoming earnings estimated to be positive.

You can also see our Videos. You can also get in touch with us via Discord.

Did you find this page helpful?

Contribute to the documentation: