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

EOD Historical Data

Upcoming Dividends

Introduction

The Upcoming Dividends dataset, provided by EODHD, offers daily alerts for US Equities that will have a dividend event within the upcoming 7 days. The data starts in January 2015 and is delivered on a daily frequency.

Compared to US Equity Security Master as a benchmark, the Upcoming Dividends dataset has a 98.56% coverage of all dividend events, while having a 99.71% precision on the exact dividend dates of the covered ones and a 99.90% precision within +/- 3 days.

For more information about the Upcoming Dividends 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 Dividends dataset:

Select Language: 
self.add_data(EODHDUpcomingDividends, "dividends")
self.add_universe(EODHDUpcomingDividends, self.selection_function)

Data Summary

The following table describes the dataset properties:

PropertyValue
Start DateJanuary 2015
Data DensitySparse
ResolutionDaily
TimezoneNew York

Example Applications

The Upcoming Dividends dataset allows traders to trade the price change due to dividends. Examples include the following strategies:

  • Short the stocks on dividend report day to earn the dividend discount on pricing.
  • Avoid volatility on securities with upcoming dividends

For more example algorithms, see Examples.

Data Point Attributes

The EODHD Upcoming Dividends dataset provides EODHDUpcomingDividends objects, which have the following attributes:

EODHDUpcomingDividends Select Language:
    Date of the dividend will happen
  • dividend_date: DateTime
    • Date of the dividend being declared
  • declaration_date: DateTime
    • Date on which the investor must be on the company's books in order to receive a dividend
  • report_date: DateTime
    • Date of the dividend being actually paid/delivered
  • payment_date: DateTime
    • Absolute payment of dividend per share
  • dividend: 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

Universe Selection

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

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

def universe_selection_filter(self, dividends: List[EODHDUpcomingDividends]) -> List[Symbol]:
    return [d.symbol for d in dividends if d.dividend_date <= self.time + timedelta(1) and d.dividend > 0.05]

For more information about universe settings, see Settings.

Requesting Data

To add Upcoming Dividends data to your algorithm, call the add_data method.

Select Language: 
class UpcomingDividendsDataAlgorithm(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(EODHDUpcomingDividends, "dividends").symbol

Accessing Data

To get the current Upcoming Dividends data, call the get(EODHDUpcomingDividends) 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_dividends = slice.get(EODHDUpcomingDividends)
    if upcomings_dividends and self._symbol in upcomings_dividends:
        upcomings_dividends_data_point = upcomings_dividends[self._symbol]
        self.log(f"{self._symbol} will pay dividend at {upcomings_dividends_data_point.dividend_date} with dividend per share of ${upcomings_dividends_data_point.dividend}")

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_dividends_data_point in slice.get(EODHDUpcomingDividends).items():
        self.log(f"{equity_symbol} will pay dividend at {upcomings_dividends_data_point.dividend_date} with dividend per share of ${upcomings_dividends_data_point.dividend}")

Historical Data

To get historical Upcoming Dividends data, call the history method with the type EODHDUpcomingDividends cast and the period of request. If there is no data in the period you request, the history result is empty.

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

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 Dividends dataset allows traders to trade the price change due to dividends. Examples include the following strategies:

  • Short the stocks on dividend report day to earn the dividend discount on pricing.
  • Avoid volatility on securities with upcoming dividends

For more example algorithms, see Examples.

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: