# Taiwan Dividend Calendar — Ex-Dates & Payouts (TWSE + TPEx) (`chamarix/taiwan-dividend-calendar`) Actor

Taiwan ex-dividend and ex-rights dates in one JSON schema: the 除權除息預告表 forecast, the 除權除息計算結果表 with prior close, reference price and the deduction actually applied, and the 股利分派情形 filings behind them — board resolution, AGM date and which reserve each dollar came from.

- **URL**: https://apify.com/chamarix/taiwan-dividend-calendar.md
- **Developed by:** [chris](https://apify.com/chamarix) (community)
- **Categories:** AI, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Taiwan Dividend Calendar — Ex-Dividend Dates, Payouts & Rights Issues (TWSE + TPEx)

Get structured JSON access to **every Taiwan ex-dividend and ex-rights date** — the forecast, the arithmetic the exchange applies on the day, and the corporate filing that produced it.

Taiwan runs one of the highest-yielding equity markets in Asia, and its dividend season is unusually concentrated: most of the market goes ex between June and September, on dates the exchanges publish weeks ahead. Three official tables describe that cycle, and this Actor normalizes all three into one flat schema.

| Record type | Chinese | What it tells you |
|---|---|---|
| **UPCOMING** | 除權除息預告表 | Which securities go ex, on what date, for how much — announced roughly a month ahead. Includes rights-issue terms. |
| **RESULT** | 除權除息計算結果表 | What actually happened on the ex-date: the last cum-dividend close, the reference price the session opened from, the deduction applied, and that day's price limits. |
| **DIVIDEND\_POLICY** | 股利分派情形 | The corporate action behind it: board resolution date, AGM date, and whether each dollar came out of earnings, the legal reserve or capital surplus. |

Both boards — TWSE listed (上市) and TPEx OTC (上櫃).

### Why this data matters

- **Ex-dates are hard, dated events.** A Taiwan stock drops by its dividend on a published morning, with a published reference price and price band. `close_before_ex`, `reference_price` and `total_deduction` give you the exact adjustment, so a backtest or a total-return series never mistakes a dividend drop for a selloff.
- **Yield strategies need lead time.** 除權息 dates are announced weeks ahead. `UPCOMING` is the market's forward calendar — everything going ex in the next month, with the cash and stock components separated.
- **The payout source changes what the dividend means.** A dividend funded from **capital surplus** (`cash_dividend_from_capital_reserve`) is a return of capital, not a share of profit — Taiwan issuers use it routinely, and a naive payout-ratio screen gets it wrong. This Actor keeps the three sources apart the way the filing does.
- **Board-approved is not shareholder-approved.** `resolution_stage` distinguishes 董事會決議 (provisional) from 股東會確認 (ratified), so you know which numbers can still change.
- **Real history, not just this season.** The TWSE result table goes back to **2003-05-05** — 18,661 ex-dates with their reference prices and price limits, served in a single request.
- **Rights issues are covered too.** 現金增資 terms — subscription ratio, price, and the split between public offering, employees and existing holders — sit in the same rows.

### Output

One record per ex-date announcement or dividend filing. Every row carries the same keys regardless of feed, so the dataset stays tabular.

```json
{
  "record_type": "RESULT",
  "market": "TWSE",
  "stock_code": "2597",
  "stock_name": "潤弘",
  "is_etf": false,
  "ex_date": "2025-08-01",
  "ex_type": "EX_RIGHTS",
  "close_before_ex": 186.0,
  "reference_price": 155.0,
  "total_deduction": 31.0,
  "limit_up": 170.5,
  "limit_down": 139.5,
  "opening_reference_price": 155.0,
  "last_report_period": "115年第1季",
  "book_value_per_share": 29.97,
  "eps": 2.38,
  "source_url": "https://www.twse.com.tw/rwd/zh/exRight/TWT49U?startDate=20250801&endDate=20260731&response=json"
}
```

```json
{
  "record_type": "DIVIDEND_POLICY",
  "market": "TWSE",
  "stock_code": "2330",
  "stock_name": "台積電",
  "cash_dividend": 7.0,
  "dividend_year": 2026,
  "dividend_period_type": "第1季",
  "dividend_period_start": "2026-01-01",
  "dividend_period_end": "2026-03-31",
  "resolution_stage": "董事會決議",
  "board_resolution_date": "2026-05-12",
  "cash_dividend_from_earnings": 7.0,
  "cash_dividend_total_amount": 181526590469,
  "net_income": 572479752038,
  "distributable_earnings": 5209341584302,
  "retained_after_distribution": 5027814993833,
  "source_url": "https://openapi.twse.com.tw/v1/opendata/t187ap45_L"
}
```

| Field | Meaning |
|---|---|
| `record_type` | `UPCOMING`, `RESULT` or `DIVIDEND_POLICY` |
| `market` | `TWSE` (listed) or `TPEX` (OTC) |
| `ex_date` / `ex_type` | The ex-date and whether it is cash (`EX_DIVIDEND`), shares (`EX_RIGHTS`) or both |
| `cash_dividend` | Declared cash dividend, NT$ per share |
| `stock_dividend_ratio` | 無償配股率 — new shares per existing share (`0.2` = 200 per 1,000 held) |
| `rights_ratio` / `rights_price` | 現金增資 subscription ratio and price |
| `close_before_ex` / `reference_price` | Last cum-dividend close and the adjusted price the ex-date opens from |
| `total_deduction` | 權值+息值 — what the exchange took off the price |
| `value_of_rights` / `value_of_dividend` | The share and cash halves of that deduction — always on TPEx, and on TWSE windows ending before 2009 |
| `limit_up` / `limit_down` | The ex-date price band |
| `book_value_per_share` / `eps` | Last reported per-share figures, printed by TWSE alongside the ex-date |
| `resolution_stage` | 董事會決議 (provisional) or 股東會確認 (ratified) |
| `board_resolution_date` / `shareholder_meeting_date` | When it was resolved and when it is ratified |
| `cash_dividend_from_earnings` / `_legal_reserve` / `_capital_reserve` | Which reserve funded each part of the payout |
| `net_income` / `distributable_earnings` / `retained_after_distribution` | The earnings context of the distribution |
| `source_url` | The exact official endpoint the row came from, so any value can be re-checked |

### What each feed covers in time

This is the one thing worth reading before your first run, because the three tables answer different questions:

- **`RESULT` on TWSE honours `startDate` / `endDate`** and reaches back to **2003-05-05**, the earliest date the exchange accepts. A 23-year range is served in a single request; an earlier start date is refused by the exchange and logged rather than silently returning nothing.
- **`UPCOMING` is a forward-looking snapshot** on both exchanges — everything announced but not yet gone ex, roughly a month out. It ignores the date range. Run it daily to accumulate a forecast history.
- **`RESULT` on TPEx is the current session only.** The OTC exchange publishes no historical version of this table, so TPEx ex-date mechanics have to be accumulated day by day. TWSE history is unaffected.
- **`DIVIDEND_POLICY` is the current filing set** — every listed company's distribution for the fiscal years still in play (about 1,150 filings), refreshed daily. It is TWSE-only: the TPEx twin of this table has not been updated since **2021-08-04**, so it is deliberately not used rather than shipped as stale data.

### Input

```json
{
  "startDate": "2026-01-01",
  "endDate": "2026-12-31",
  "recordTypes": ["UPCOMING", "RESULT", "DIVIDEND_POLICY"],
  "markets": ["TWSE", "TPEX"],
  "excludeEtfs": true
}
```

Example — just the forward calendar, ordinary shares only:

```json
{
  "startDate": "2026-01-01",
  "recordTypes": ["UPCOMING"],
  "excludeEtfs": true
}
```

Example — two decades of TWSE ex-dates for two tickers:

```json
{
  "startDate": "2003-05-05",
  "endDate": "2026-07-31",
  "recordTypes": ["RESULT"],
  "markets": ["TWSE"],
  "stockCodes": ["2330", "2412"]
}
```

Leave `recordTypes` or `markets` empty for all of them.

### Pricing & cost control

Pay per result: **$0.50 / 1,000 records**.

- The forward calendar alone, both markets: ~220 records ≈ $0.11
- Every dividend filing on the market: ~1,150 records ≈ $0.58
- One year of TWSE ex-date results: ~1,460 records ≈ $0.73
- The default run — this year's results, the forward calendar and every filing: ~2,400 records ≈ $1.20
- The entire TWSE ex-date archive back to 2003: 18,661 records ≈ $9.33

`excludeEtfs: true` removes roughly a fifth of the calendar — 00-prefixed ETFs and ETNs distribute monthly or quarterly and crowd the list. `stockCodes` narrows to a specific name for a few cents.

### Data source & reliability

- Direct from the official TWSE and TPEx ex-dividend feeds — no third-party intermediaries
- **Every value cross-checked against a second official endpoint.** Both exchanges publish these tables twice through independent endpoints; each run compares them field by field and logs any disagreement. Verified 2026-08-03: 101 shared TWSE securities and 94 shared TPEx securities agreed on every field, as did all 5 TPEx result rows.
- **Built-in arithmetic checks.** The reference price must equal the prior close less the published deduction; where the exchange splits the deduction, 權值 + 息值 must equal its own total; and for a company paying both cash and stock, the two distribution totals must imply the same share count. Verified across the entire 18,661-row TWSE archive and all 1,148 current filings — **one** row fails, and it is reported rather than quietly patched (see below).
- **Both of the exchange's column layouts are handled.** TWSE serves the result table with 權值 and 息值 split out for a window ending on or before 2008, and with the combined figure alone from 2009 on. Columns are resolved by header name, not position, so neither layout — nor a future insertion — can be silently mis-mapped.
- **Spot-verified against independent price data.** Nine ex-dates across all three ex-types were checked against the TWSE daily quote feed: `close_before_ex` matched the prior session's official close exactly in every case. Dividend totals reproduce the officially registered share count — 台積電's NT$181,526,590,469 ÷ NT$7.00 is 25,932,370,067 shares, to the share.
- Column-layout guard on all five feeds: if either exchange changes its schema, the run fails loudly instead of publishing silently mis-mapped values
- Market holidays, empty windows and future dates return no rows rather than failing
- Prose the exchanges print where a number belongs — an ETF distribution still to be announced, a rights price not yet fixed — becomes `null` and is preserved verbatim in `note` rather than guessed at
- **Two things worth knowing about the numbers**, both verified rather than assumed:
  - `value_of_dividend` (息值) is the deduction the exchange applied, which is not always identical to the declared `cash_dividend`. Over 114年度 they matched exactly for 516 of 581 listed companies; the rest differ, mostly by under 2%. Use `cash_dividend` for the declared payout.
  - A rights issue subscribed above the market **raises** the theoretical price: `total_deduction` goes negative and `reference_price` lands above `close_before_ex`. Two of the 1,460 ex-dates in the year to 2026-07-31 did this (國喬 1312 and its preferred 1312A, both 2026-06-11). Real data, not a parse error.
  - On nine pre-2009 rows the exchange printed that adjustment **unsigned**. Since both prices in `close_before_ex − reference_price` are themselves published, the sign is recoverable without guessing, and those rows are corrected with the reason recorded in `note`. One row cannot be: 京城銀 2809 on 2005-09-01 hides its sign inside a single component (權 −0.03 + 息 0.20, published combined as 0.23), which a query spanning 2009 never receives. That row ships exactly as the exchange published it and is logged as an identity violation — 1 of 18,661.
- Published after each session's close; the forecast table updates as companies file

### Use cases

- **Dividend and high-yield screeners** — rank the forward calendar by `cash_dividend` against price, filtering out capital-surplus payouts
- **Total-return and backtest correction** — apply `total_deduction` on `ex_date` so a dividend drop is never read as a decline
- **Dividend-capture timing** — the ex-date, its reference price and its price band, for every name in the season
- **Payout-quality research** — `cash_dividend_from_capital_reserve` against `net_income` separates issuers distributing profit from issuers returning capital
- **Rights-issue monitoring** — subscription ratios, prices and allocations as they are announced
- **Corporate-governance timelines** — board resolution → AGM → ex-date, per company per fiscal period

### Related Actors

- [Taiwan Margin Trading](https://apify.com/chamarix/taiwan-margin-trading) — 融資融券 balances, which spike around ex-dates
- [Taiwan Short Sale & SBL Balance](https://apify.com/chamarix/taiwan-sbl-short-sale-balance) — short interest that must be covered before book closure
- [Taiwan Stock Alerts](https://apify.com/chamarix/taiwan-stock-alerts) — watch-list, disposition and short-sale suspension announcements
- [Taiwan Monthly Revenue](https://apify.com/chamarix/taiwan-monthly-revenue) — the earnings that fund next year's dividend
- [TWSE Institutional Trades](https://apify.com/chamarix/twse-institutional-trades) — daily foreign/trust/dealer flows, main board
- [TPEx Institutional Trades](https://apify.com/chamarix/tpex-institutional-trades) — same for the OTC market
- [TAIFEX Institutional Traders](https://apify.com/chamarix/taifex-institutional-derivatives) — futures and options positioning
- [Taiwan Shareholding Dispersion (TDCC)](https://apify.com/chamarix/tdcc-shareholding-dispersion) — weekly retail vs whale ownership

# Actor input Schema

## `startDate` (type: `string`):

Start date in YYYY-MM-DD format. Applies to the RESULT feed on TWSE only — UPCOMING, DIVIDEND\_POLICY and the TPEx tables are published as a current snapshot and ignore the range. TWSE serves ex-date history back to 2003-05-05 and refuses anything earlier.

## `endDate` (type: `string`):

End date in YYYY-MM-DD format (inclusive). Leave empty to query only the start date. Ranges of several years are served in a single request.

## `recordTypes` (type: `array`):

Which of the three official publications to collect. Leave empty for all three.

## `markets` (type: `array`):

Which boards to cover. Leave empty for both. Only TWSE files 股利分派情形; the TPEx twin of that table has not been updated since 2021 and is deliberately not used.

## `stockCodes` (type: `array`):

Optional list of security codes to keep (e.g., \['2330', '2412']). Leave empty for every security going ex-dividend.

## `excludeEtfs` (type: `boolean`):

Drop 00-prefixed codes — ETFs, ETNs and their bond and leveraged variants. They make up roughly a fifth of the ex-dividend calendar and pay monthly or quarterly distributions rather than corporate dividends; turn this on to keep ordinary shares only.

## Actor input object example

```json
{
  "startDate": "2026-01-01",
  "endDate": "2026-12-31",
  "recordTypes": [
    "UPCOMING",
    "RESULT",
    "DIVIDEND_POLICY"
  ],
  "markets": [
    "TWSE",
    "TPEX"
  ],
  "stockCodes": [],
  "excludeEtfs": false
}
```

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startDate": "2026-01-01",
    "endDate": "2026-12-31",
    "recordTypes": [
        "UPCOMING",
        "RESULT",
        "DIVIDEND_POLICY"
    ],
    "markets": [
        "TWSE",
        "TPEX"
    ],
    "stockCodes": []
};

// Run the Actor and wait for it to finish
const run = await client.actor("chamarix/taiwan-dividend-calendar").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startDate": "2026-01-01",
    "endDate": "2026-12-31",
    "recordTypes": [
        "UPCOMING",
        "RESULT",
        "DIVIDEND_POLICY",
    ],
    "markets": [
        "TWSE",
        "TPEX",
    ],
    "stockCodes": [],
}

# Run the Actor and wait for it to finish
run = client.actor("chamarix/taiwan-dividend-calendar").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startDate": "2026-01-01",
  "endDate": "2026-12-31",
  "recordTypes": [
    "UPCOMING",
    "RESULT",
    "DIVIDEND_POLICY"
  ],
  "markets": [
    "TWSE",
    "TPEX"
  ],
  "stockCodes": []
}' |
apify call chamarix/taiwan-dividend-calendar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=chamarix/taiwan-dividend-calendar",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/vm5wwfgU6j1dmQ0dz/builds/rdEnfSoqwCckLdxzG/openapi.json