Get regular and special dividend data

Dividends

Info

The Databento team is currently working on this article.

Overview

Dividends are a form of capital distribution paid to shareholders. They can be issued in various forms, most commonly as cash payments or additional shares of stock. Companies may pay dividends on a regular basis, such as quarterly, or as special one-off dividends that are typically issued due to exceptional earnings or significant events.

Requesting dividends

This example demonstrates how to use the Reference client to retrieve all Costco dividends from the beginning of 2019 through 2020. Costco is a good example of a company that pays a regular quarterly dividend. Additionally, we can observe the inclusion of a special dividend during this period.

We can query for dividends specifically by filtering for the DIV (Dividend) event type. Once we obtain the records, we can filter the relevant columns for analysis.

import databento as db

# Create a reference client
ref_client = db.Reference(key="$YOUR_API_KEY")

# Request corporate actions
df_raw = ref_client.corporate_actions.get_range(
    symbols=["COST"],
    start="2019",
    end="2021",
    index="ex_date",
    events=["DIV"],
    countries=["US"],
)

# Filter relevant columns
columns = [
    "record_date",
    "payment_date",
    "payment_type",
    "marker",
    "frequency",
    "gross_dividend",
    "operating_mic",
    "isin",
    "symbol",
    "issuer_name",
]
df = df_raw[columns]

df.head(10)

Result

           record_date payment_date payment_type marker frequency  gross_dividend operating_mic          isin symbol            issuer_name
ex_date
2019-02-07  2019-02-08   2019-02-22            C    INT       QTR            0.57          XNAS  US22160K1051   COST  Costco Wholesale Corp
2019-05-09  2019-05-10   2019-05-24            C    INT       QTR            0.65          XNAS  US22160K1051   COST  Costco Wholesale Corp
2019-08-29  2019-08-30   2019-09-13            C    INT       QTR            0.65          XNAS  US22160K1051   COST  Costco Wholesale Corp
2019-10-31  2019-11-01   2019-11-15            C    INT       QTR            0.65          XNAS  US22160K1051   COST  Costco Wholesale Corp
2020-02-06  2020-02-07   2020-02-21            C    INT       QTR            0.65          XNAS  US22160K1051   COST  Costco Wholesale Corp
2020-04-30  2020-05-01   2020-05-15            C    INT       QTR            0.70          XNAS  US22160K1051   COST  Costco Wholesale Corp
2020-07-30  2020-07-31   2020-08-14            C    INT       QTR            0.70          XNAS  US22160K1051   COST  Costco Wholesale Corp
2020-10-29  2020-10-30   2020-11-13            C    INT       QTR            0.70          XNAS  US22160K1051   COST  Costco Wholesale Corp
2020-12-01  2020-12-02   2020-12-11            C    SPL        UN           10.00          XNAS  US22160K1051   COST  Costco Wholesale Corp

Special dividends

Special dividends are one-time or irregular dividend payments made by a company, typically in addition to regular dividend distributions. Unlike regular dividends, which are usually paid on a fixed schedule (e.g., quarterly or annually), special dividends are declared in response to exceptional circumstances, such as significant financial gains, asset sales, or other extraordinary events.

For example, consider the special dividend paid by Costco on December 11, 2020:

marker was SPL (Special)

frequency was UN (Unspecified)

The dividend was paid less than a month after the previous quarterly dividend

Fields

The table below provides detailed descriptions for each dividend-specific field found in the dynamic info JSON fields.

Field	Description
`marker`	The dividend marker. See the MARKER enum lookup table.
`frequency`	The dividend frequency. See the FREQ enum lookup table.
`declaration_date`	The date the dividend was announced by the issuer.
`period_end_date`	The end of the financial period for which the dividend is being paid.
`foreign_ex_date`	The date on which the US dollar rate to `currency` value was taken.
`ex_date2`	This is the ex date value for stock component of a dividend with a `payment_type` of (B)oth stock and cash. The main `ex_date` field will be for the cash payment portion of the same record.
`payment_date2`	This is the payment date value for stock component of a dividend with a `payment_type` of (B)oth stock and cash. The main `payment_date` field will be for the cash payment portion of the same record.
`tba_flag`	The company intends to pay a dividend but the details are yet to be announced.
`nil_dividend`	A real dividend event but of zero payrate.
`div_rescind`	A dividend event but of zero payrate.
`decl_currency`	The declared currency - ISO 4217.
`decl_gross_amount`	The declared gross amount.
`approx_flag`	If dividend is temporarily an approximate value.
`tax_rate`	The domestic withholding tax rate.
`coupon`	In countries where coupons are to be submitted to obtain a benefit this field is useful.
`coupon_id`	The coupon ID.
`div_rate`	The rate of dividend as a percentage of par value.
`cur_pair`	Identifies the different currencies involved for the FX rate to be applied - ISO 4217.
`dep_fees`	Depositary Fees - applies only to `DR` dividend.
`dep_fees_currency`	Depositary Fees currency - ISO 4217.
`rescind_cash_div`	If cash dividend cancelled.
`rescind_stock_div`	If stock dividend cancelled.
`usd_rate_to_currency`	The US dollar exchange rate for dividend currency.
`div_postponed`	Indicating postponement of dividend payment.

Dividend types

The marker field specifies the type of dividend. See MARKER enum lookup table for possible values.

The table below provides detailed descriptions for each dividend type:

Value	Description
`ANL`	Annual: Refers to a dividend that is paid once per year.
`ARR`	Arrears: Denotes a dividend payment made to cover missed or deferred dividends from previous periods.
`CG`	Capital Gain: Indicates a dividend that is categorized as a gain realized from the appreciation of an asset.
`CGL`	Capital Gain Long Term: Refers to a capital gain from an asset held for more than a year before being sold, often benefiting from preferential tax treatment.
`CGS`	Capital Gain Short Term: Refers to a capital gain from an asset held for less than a year before being sold, typically subject to higher tax rates.
`FNL`	Final: Indicates that this dividend is the last payment related to a particular series or event.
`INS`	Installment: Refers to dividends paid in multiple payments over a period rather than a single lump sum.
`INT`	Interim: A dividend paid between regular annual dividends, often reflecting earnings for a part of the year.
`ISC`	Interest on Capital: Represents payments made as interest on the capital invested in a company or financial product.
`MEM`	Memorial: Indicates a dividend paid in memory of an individual, often reflecting a special purpose or tribute.
`QTR`	Quarterly: Refers to dividends paid every three months.
`REG`	Regular: Denotes dividends that are paid at regular intervals, typically on a fixed schedule.
`SMA`	Semi-annual: Refers to dividends paid twice a year.
`SPL`	Special: Indicates a one-time or irregular dividend payment, often separate from regular dividends.
`SUP`	Supplementary: Refers to additional dividends paid in addition to regular payments, usually reflecting extra earnings or adjustments.
`UN`	Unspecified: Indicates that the dividend type is not defined or categorized under the specified options.
`VAR`	Variable: Refers to dividends that can vary in amount or frequency, based on company performance or other factors.

Dividend frequency

The frequency field specifies the frequency of dividend payments or occurrences. See FREQ enum lookup table for possible values.

The table below provides detailed descriptions for each dividend frequency:

Value	Description
`28D`	28 Days: Dividend occurs every 28 days.
`35DAY`	Every 35 Days: Dividend occurs every 35 days.
`BIM`	Bi-Monthly: Dividend occurs every two months.
`DLY`	Daily: Dividend occurs every day.
`FNL`	Final: The last dividend in a series.
`INT`	Interim: Dividend occurring between regular annual payments.
`INTONMAT`	Arrears: Interest paid upon the maturity of a financial product.
`INTONTRIG`	Interest on Trigger: Interest paid when a specific trigger condition is met.
`IRG`	Irregular: Dividend occurs at irregular intervals.
`ITM`	Interest on Maturity: Interest paid upon the maturity of a financial product.
`MNT`	Monthly: Dividend occurs every month.
`QTR`	Quarterly: Dividend occurs every three months.
`SMA`	Semi-Annual: Dividend occurs twice a year.
`TRM`	Trimesterly: Dividend occurs every four months (three times a year).
`UN`	Unspecified: Dividend frequency is not defined or categorized.
`WKL`	Weekly: Dividend occurs every week.