The wealthAPI dividends API
Dividend calculations have an intrinsic complexity due to the following factors
differences between expected and actual values due to domestic taxation and foreign withholding taxation.
payout delays due to bank processing times
flawed or incomplete master data
varying exchange rates for foreign currency dividends
changes in payout intervals
cancellation of dividends for stocks traded around the payout date
Our dividend API does address these challenges and combines actual data - this is: what arrived on the bank account - with the theoretically expected dividends.
Dividends for a single investments
The /api/v1/dividends endpoints allows to retrieve dividends for an ISIN or for one or many investments. If dividends for a specific investment are requested, the API will return expected values in the Dividend entity. Also, it will return the actual value sin the existingTransaction entity (see image below).
Should foreign withholding taxation apply, as is the case for all US stocks, then differences between the values provided in the Dividend entity and the existingTransaction are expected as many banks do not report taxes via the multi banking APIs.
Comparison between theoretical and actual values allow conclusions (or better: estimates) on the actual tax paid.
Dividend timeline
The dividend timeline APIs allow for seamless navigation between past, current and future dividend payouts. To this end, historic data is combined with predictions, thus leading to a break-less transition between historic and future data. Please refer to the GET/v1/dividends/timeline endpoint for details.
We also provide a summarized timeline that does aggregate values per year. This is useful to keep the UX clean for larger portfolios. The summarized endpoint will aggregate all yearly payments into one value. Thus - e.g. for Microsoft - you would see only one value per year instead of the usual four quarterly dividend payments. Please refer to the GET /v1/dividends/timeline/summary endpoint for details.
How are dividend predictions calculated
We use a linear prediction algorithm to calculate predicted dividends. This is, we take the average change over the last years and from this predict a linear increase / decrease. When doing so, we ignore special dividends.
Our prediction algorithm also handles special cases like e.g. the corona crisis, in which dividends have not been payed out for a certain year. The following figure illustrates linear dividend prediction:
Adding analyst estimates
We allow adding analyst estimates and also combining analyst estimates with linear prediction, thus improving the overall data quality. This however requires your licensed dividend provider to supply analyst estimates.