How to Build a Dividend Yield Calculator and Payout Tracker App

A dividend tracker answers two questions. How much income will this portfolio pay me, and when does the next payment land? A spreadsheet can do it until you hold fifteen stocks, forget to update one, and miss an ex-dividend date.

This guide builds a small Python tracker on SteadyAPI. It reads your holdings, pulls live quotes, calculates yield and yield on cost, and lists upcoming payouts in date order. It also deals with a quirk you will hit on day one: not every stock has dividend history on the same endpoint.

Prerequisites

  • A SteadyAPI API key from steadyapi.com. The Free plan ($0) works for a small portfolio. Read the request count section before you scale up.
  • Python 3.8+ with requests.

Which data comes from where

You need two endpoints.

Quotes: GET https://api.steadyapi.com/v1/markets/stock/quotes (weight 2). Send up to 200 symbols in ticker, separated by commas. For each stock it returns, among other fields:

  • regularMarketPrice: the last price, as a number.
  • dividendRate: the forward annual dividend per share.
  • trailingAnnualDividendRate: what the stock paid over the last twelve months.
  • dividendYield: the yield as a percentage. 0.31 means 0.31%.
  • dividendDate: the next payment date, as a Unix timestamp.

Be careful with trailingAnnualDividendYield. It is a fraction, so 0.003 means 0.3%. We calculate yield ourselves to avoid mixing the two.

Dividend calendar: GET https://api.steadyapi.com/v1/markets/calendar/dividends (weight 1). It has two modes:

  • With date (YYYY-MM-DD): every company with a dividend event that day.
  • With ticker: that company's dividend history, newest first. Each row has exOrEffDate, amount, declarationDate, recordDate and paymentDate. Dates are MM/DD/YYYY strings and amount is a string like "$0.27". The meta object adds exDividendDate, dividendPaymentDate and annualizedDividend.

The history rows include dividends that are already declared but not yet paid. That is how you get exact upcoming payouts.


The catch: history is Nasdaq-only

The ticker mode returns history for Nasdaq-listed stocks such as AAPL and MSFT. For NYSE names such as KO or JNJ it returns a normal HTTP 200 with {"success": false, "message": "No data returned."}.

Do not treat that as a crash. The tracker catches it and falls back to the quote's dividendDate. You still get the payment date. You lose the exact amount and the ex-dividend date for those stocks. Yield and annual income come from the quote either way, so they stay complete.


The script

Edit HOLDINGS with your own tickers, share counts and average cost per share.

from datetime import date, datetime, timedelta, timezone

import requests

API_KEY = "YOUR_STEADYAPI_KEY"
BASE = "https://api.steadyapi.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

HOLDINGS = [
    {"ticker": "KO", "shares": 50, "cost": 55.00},
    {"ticker": "AAPL", "shares": 20, "cost": 150.00},
    {"ticker": "JNJ", "shares": 15, "cost": 160.00},
]


def get(path, **params):
    r = requests.get(f"{BASE}{path}", headers=HEADERS, params=params, timeout=30)
    r.raise_for_status()
    data = r.json()
    if data.get("success") is False:
        raise RuntimeError(data.get("message", "Request failed"))
    return data


def money(value):
    return float(str(value).replace("$", "").replace(",", ""))


def us_date(value):
    return datetime.strptime(value, "%m/%d/%Y").date()


def dividend_history(ticker):
    try:
        return get("/v1/markets/calendar/dividends", ticker=ticker)["body"]
    except RuntimeError:  # "No data returned" for stocks that pay nothing
        return []


tickers = ",".join(h["ticker"] for h in HOLDINGS)
quotes = {q["symbol"]: q for q in get("/v1/markets/stock/quotes", ticker=tickers)["body"]}

today = date.today()
year_ago = today - timedelta(days=365)
total_income = total_value = total_cost = 0.0
upcoming = []

print(f"{'Ticker':7}{'Price':>9}{'Rate':>7}{'Yield':>8}{'YoC':>8}{'Income/yr':>11}{'Paid 12m':>10}")
for h in HOLDINGS:
    q = quotes.get(h["ticker"])
    if not q:
        print(f'{h["ticker"]:7} no quote returned, skipping')
        continue

    price = q["regularMarketPrice"]
    rate = q.get("dividendRate") or q.get("trailingAnnualDividendRate") or 0.0
    income = h["shares"] * rate

    paid_12m = 0.0
    history = dividend_history(h["ticker"])
    for p in history:
        try:
            pay_date, ex_date = us_date(p["paymentDate"]), us_date(p["exOrEffDate"])
        except (KeyError, ValueError):
            continue  # a row without usable dates
        amount = h["shares"] * money(p["amount"])
        if pay_date >= today:
            upcoming.append((pay_date, h["ticker"], amount, ex_date))
        elif pay_date >= year_ago:
            paid_12m += amount

    if not history and q.get("dividendDate"):
        # No history (non-Nasdaq listing): fall back to the quote's next payment date
        pay_date = datetime.fromtimestamp(q["dividendDate"], timezone.utc).date()
        if pay_date >= today:
            upcoming.append((pay_date, h["ticker"], None, None))

    total_income += income
    total_value += h["shares"] * price
    total_cost += h["shares"] * h["cost"]
    paid = f"{paid_12m:.2f}" if history else "n/a"
    print(f'{h["ticker"]:7}{price:>9.2f}{rate:>7.2f}{rate / price * 100:>7.2f}%'
          f'{rate / h["cost"] * 100:>7.2f}%{income:>11.2f}{paid:>10}')

print(f"\nPortfolio yield: {total_income / total_value * 100:.2f}%   "
      f"yield on cost: {total_income / total_cost * 100:.2f}%   "
      f"about {total_income / 12:.2f} a month")

print("\nUpcoming payouts:")
for pay_date, ticker, amount, ex_date in sorted(upcoming):
    if amount is None:
        print(f"{pay_date:%b %d, %Y}  {ticker:6} {'n/a':>8}  (date only)")
        continue
    note = "ex-date passed" if ex_date <= today else f"buy before {ex_date:%b %d}"
    print(f"{pay_date:%b %d, %Y}  {ticker:6} {amount:>8.2f}  ({note})")

Sample output

Ticker     Price   Rate   Yield     YoC  Income/yr  Paid 12m
KO         97.64   2.12   2.17%   3.85%     106.00       n/a
AAPL      355.62   1.08   0.30%   0.72%      21.60     21.20
JNJ       280.88   5.36   1.91%   3.35%      80.40       n/a

Portfolio yield: 1.28%   yield on cost: 2.55%   about 17.33 a month

Upcoming payouts:
Nov 16, 2026  AAPL       5.40  (buy before Nov 12)
Dec 08, 2026  JNJ         n/a  (date only)
Dec 15, 2026  KO          n/a  (date only)

Your numbers will differ. They move with the market.


How to read it

  • Yield is the annual dividend divided by today's price. It shifts every time the price does.
  • YoC is yield on cost. It divides the same dividend by what you paid, so it shows what the position earns for you.
  • Paid 12m adds up the payments dated in the last 365 days. Compare it with Income/yr. A gap usually means the company raised its dividend recently. In the sample, AAPL paid 21.20 and the forward rate says 21.60.
  • Buy before is the ex-dividend date. You must own the shares before that day to receive the payment.

The forward rate is a projection. If a company cuts or skips a payment, the forward figure is wrong until the data updates. Treat it as an estimate.


Count your requests

One run costs 2 for the quote call, plus 1 per holding for the history call. That is 5 requests for the three holdings above. On the Free plan, capped at 20 requests a day, you can track about 18 stocks once a day. A failed history call returns HTTP 200, so it still counts.

Dividends change a few times a year, so run it once a day or once a week, not every minute. If you only want yield and annual income, skip the history calls. One quote request covers up to 200 holdings.


Next steps

  • Save the results. Write each run to a CSV or SQLite table to see income grow over time.
  • Add a reminder. Email or message yourself when a payout is within three days. The Slack and Discord bot guide shows how to schedule one.
  • Scan the market. Call the calendar with date to see who goes ex-dividend on a given day. The calendar automation guide and the dividends, splits and offerings post cover that.
  • Ask in plain English. Connect your editor to the SteadyAPI MCP server at https://api.steadyapi.com/mcp and ask for a stock's dividend history without writing code.

Conclusion

The quote endpoint gives you the yield and annual income. The calendar endpoint gives you exact payment dates where it has history. A short fallback covers the rest.

Create a free account at steadyapi.com (no card required) and run the script on your own holdings. Then read the API documentation for every parameter and ready-made examples in cURL, JavaScript, PHP, and Python.