What does a dividend look like as a row of data?

A dividend feels like one event. In data it is four dates and two amounts, and if you pick the wrong one of each you will produce a number that is confidently, invisibly wrong.

The record

/div/{ticker} returns an array. Here is one real element, Apple's first payout of 2020, with the last payout of the same year beneath it for contrast:

The parameters are from, to (both YYYY-MM-DD) and fmt (json or csv, default json).

The four dates, in the order they happen

1. declarationDate — the board announces it. Nothing has happened to anyone's account yet.
2. date — the ex-dividend date. Buy on or after this day and you do not receive this dividend. This is the day the market prices it in, and it is why the price typically opens lower by roughly the dividend amount.
3. recordDate — the registry snapshot of who is owed the money. Under the T+2 settlement of the time it fell one business day after the ex-date — here Friday to Monday, which is three calendar days but only one trading one. The rule is the cycle minus a day, so a mid-week T+2 dividend has its record date the next morning, not two days later. Since US settlement moved to T+1 on 28 May 2024 the two coincide: Apple's August 2024 payout has both on 2024-08-12.
4. paymentDate — the cash actually arrives. Here, six days after the ex-date.

The array is keyed on date, the ex-date. That is the field the corporate action is filed under, and it is the correct one to join against price history — because the ex-date is the day the price responded. Join on paymentDate instead and every dividend lands several days after the price move it caused. Over a decade of quarterly payouts that is 40 small misalignments, none of which will look like a bug.

The two amounts, and the trap between them

Look at Apple's four 2020 dividends as returned by the API:

Apple split 4-for-1 on 2020-08-31. Every dividend paid before that date is reported twice: unadjustedValue is what a shareholder actually received per share at the time, and value is that amount restated onto today's share count. 0.77 ÷ 4 = 0.1925. 0.82 ÷ 4 = 0.205. The November payout came after the split, so the two fields are identical.

Now the trap. Sum the unadjustedValue column: 0.77 + 0.82 + 0.82 + 0.205 = 2.615. That number describes nothing. It adds three payments on pre-split shares to one payment on post-split shares, as if they were the same unit. Sum the value column instead: 0.1925 + 0.205 + 0.205 + 0.205 = 0.8075 per share, all in today's units, and the figure is meaningful.

Use value for any calculation spanning time. Use unadjustedValue only to reconcile against a historical statement or a broker's record of what was actually paid.

Try it now

1. Here is the whole of /div/AAPL.US?from=2020-01-01&to=2020-12-31, both amounts on every row. Check it against the table above, then confirm the 4:1 arithmetic yourself on each row and say which row needs no division and why.

2. Over ten years, /div/AAPL.US?from=2016-01-01&to=2025-12-31 held 40 payouts on 28 September 2026, 19 of them before the split. The two columns summed as below. Say which of the two is a per-share figure in today's units, and use the 4:1 arithmetic from the table above to explain where the extra 9.72 in the other came from. That gap is the size of the error the wrong column would have introduced.