Dividend-Capture Event Database With Recovery Data

A useful dividend-capture database separates the cash dividend, the ex-day price give-back, the net capture, and the later recovery path for every event.

Alphanume's Dividend Capture dataset stores historical and upcoming ex-dividend events. Historical rows include the cash amount, cum-day close, ex-day open and close, price-drop ratios, net capture, breakeven level, recovery status, and recovery timing. Upcoming rows carry the schedule first and fill the outcome fields only after prices become observable.

That separation prevents the basic mistake in dividend-capture research: counting the dividend as income while ignoring the mechanical ex-day price adjustment. A $1 dividend paired with a $1 price decline has a very different gross outcome from a $1 dividend paired with a $0.30 decline, even before taxes, spreads, commissions, and slippage.

Keep the four measurements distinct

drop_ratio_close=1 means the close-to-close give-back matched the cash dividend. A value below one means less than the full dividend was lost by the ex close, while a value above one means the price drop exceeded it. The ratio is descriptive and can be negative when the stock rises enough on the ex date.

Breakeven recovery and full-price recovery are also different. The breakeven level subtracts the cash dividend from the cum close, while recovery to the original cum-dividend price asks the stock to regain the entire marked price decline. Report both clocks when capital duration is part of the thesis.

Query settled historical events

The endpoint is GET /v1/dividend-capture. Use a completed date range for recovery research and keep pending rows in the denominator. Filtering only recovery_status=recovered answers a conditional question and cannot estimate the overall recovery rate.

import os
import requests

response = requests.get(
    "https://api.alphanume.com/v1/dividend-capture",
    headers={"X-API-Key": os.environ["ALPHANUME_API_KEY"]},
    params={"date_gte": "2025-01-01", "date_lte": "2025-12-31"},
    timeout=30,
)
response.raise_for_status()
events = response.json()["data"]

required = {
    "date", "ticker", "cash_amount", "drop_ratio_close",
    "net_capture_pct", "recovery_status", "bars_observed",
}
assert all(required.issubset(row) for row in events)

The database tracks recovery over a 20-session window and exposes recovered_within_1d, 3d, 5d, 10d, and 20d flags. Recent events can remain pending with fewer than 20 bars. Treat those rows as censored at the available observation count rather than labeling them failures early.

Read the lifecycle correctly

Rows change as the event resolves. A forward row begins with schedule metadata, moves to pending after the ex date settles, and becomes final after recovery or the observation window ends. Save the retrieval date when simulating a live screen so later recovery information does not leak into the original decision.

Use the forward calendar separately

Set upcoming=true to request future ex-dividend dates. The default horizon is seven days and future_days is capped at 120. The forward calendar intentionally bypasses the historical delay window, while its ex-day and recovery fields remain empty because those outcomes do not exist yet.

A current screen can join upcoming schedule rows to each ticker's prior settled history, but it must define how much history is available as of the screen date. Do not use a later row's final recovery status or future price path when scoring an upcoming event.

Account for what gross data omits

• Taxes. Dividend qualification, withholding, account type, and jurisdiction are user-specific.
• Execution. Cum-day entry and ex-day exit prices may differ from closes or opens.
• Market movement. Ex-day returns include broad and company-specific news beyond the dividend adjustment.
• Selection. A clean historical row does not guarantee a future event will behave similarly.
• Capital use. Recovery time affects how long cash and risk remain tied to the position.

Historical net capture is gross of the reader's taxes and trading costs. A positive median cannot establish guaranteed income, and a recovered position can still have unattractive opportunity cost or interim drawdown. The proof page supplies published product evidence, not a promise about an individual implementation.

Build one recovery audit

Read the Dividend Capture field reference, pull one completed year, and publish counts by status before any average. Compare open and close drop ratios, net capture, and recovery curves by regular versus special dividends, while keeping frequency, yield, and bars observed visible.

Then select 20 source events across fast recovery, slow recovery, and no recovery. Recalculate breakeven from cum_close - cash_amount, verify the recovery date against the observed bars, and add realistic transaction costs and tax scenarios separately. That audit turns a dividend calendar into a reproducible event database.