Taiwan Foreign & Mainland Shareholding (TWSE + TPEx)

Get structured JSON access to daily foreign ownership for every Taiwan-listed and OTC security — how many shares overseas and mainland-Chinese investors hold, how many they may still buy, and how close they are to the legal ceiling.

Institutional trade data tells you the flow — who bought and sold today. This Actor gives you the stock: the accumulated position, per security, per day, straight from the exchanges' own 外資及陸資投資持股統計 and 僑外資及陸資持股比例排行表 reports.

Why this data matters

• Foreign ownership is the single most-watched positioning metric in Taiwan equities. TSMC sits around 69% foreign-held; a multi-point drift in that number is a macro event, not a stock story.
• Quota squeezes are real and tradeable. Telecoms, broadcasting, aviation, shipping and defence names carry statutory ceilings — 49%, 49.99%, 19%, even 0%. When foreign investors approach the cap, buying pressure has nowhere to go and the shares trade at a premium. quota_utilization_pct measures exactly that, and capRestrictedOnly narrows the run to the ~29 securities where it can happen.
• Ownership stock vs. institutional flow. Cross-referenced with daily buy/sell data, the change in held shares separates genuine accumulation from intraday churn.
• Non-trading changes are flagged. The TWSE marks rows whose holdings moved because of a capital increase, a GDR conversion or a corrected filing rather than market trading — so you can exclude them before computing a flow.
• 20+ years of history. TWSE back to 2004-02-11, TPEx back to 2007-05-02, at daily granularity, with the pre-2009 layout (before mainland investors were admitted at all) parsed correctly.

Output

One record per security per trading day, 21 normalized fields. All share counts are in shares (股), not lots.

{
  "date": "2026-08-07",
  "market": "TWSE",
  "stock_code": "2330",
  "stock_name": "台積電",
  "isin": "TW0002330008",
  "issued_shares": 25932370067,
  "foreign_held_shares": 17931083542,
  "foreign_available_shares": 8001286525,
  "foreign_held_pct": 69.14,
  "foreign_available_pct": 30.85,
  "foreign_ownership_cap_pct": 100.0,
  "mainland_ownership_cap_pct": 100.0,
  "quota_utilization_pct": 69.1456,
  "reserved_shares": 0,
  "available_shares_matches_formula": true,
  "rank": null,
  "change_reason_code": null,
  "change_reason": "Ordinary secondary-market trading by foreign/mainland investors",
  "last_reported_change_date": "2026-05-26",
  "note": null,
  "held_pct_recomputed": 69.145564
}

Field	Meaning
issued_shares	發行股數 — shares issued, as filed with the exchange
foreign_held_shares	全體外資及陸資持有股數 — shares held by all foreign + mainland investors
foreign_available_shares	尚可投資股數 — shares they may still buy before the cap binds
foreign_held_pct / foreign_available_pct	The two official percentages, as printed
foreign_ownership_cap_pct	法令投資上限比率 — statutory ceiling on combined foreign + mainland ownership
mainland_ownership_cap_pct	陸資法令投資上限比率 — separate ceiling for mainland investors alone (TWSE, 2009+)
quota_utilization_pct	held / (issued × cap) — how much of the legal quota is used
reserved_shares	Shares withheld from availability for approved-but-unissued GDRs and similar
available_shares_matches_formula	false on the ~0.6% of rows carrying reserved shares
rank	TPEx publishes its table ranked by holding percentage; TWSE does not (null)
change_reason_code / change_reason	TWSE footnote 2–5, explaining a non-trading change vs. the previous session
last_reported_change_date	When the company last filed a holdings change (TWSE)
held_pct_recomputed	Holding percentage at 6 decimals, for screens where 2dp is too coarse

The metric that isn't obvious

For the ~98% of securities with a 100% cap, quota_utilization_pct is just the holding percentage. For the rest it is a different number entirely — and it is the one that matters:

Security	Foreign held	Statutory cap	Quota used
中華電 2412 Chunghwa Telecom	17.28%	49%	35.28%
長榮 2603 Evergreen Marine	21.78%	49.99%	43.59%
萬海 2615 Wan Hai Lines	44.78%	49.99%	89.59%
新興 2605 Sincere Navigation	49.75%	49.99%	99.54%

Sincere Navigation has 0.23% of its shares left before foreign investors are legally shut out. A screener sorting on raw holding percentage would never surface it above TSMC.

Data integrity

The exchanges print both percentages alongside the share counts they derive from, which makes the parse self-checking. On every run, for every row:

• foreign_held_pct must equal held / issued, floored to 2 decimals — matched 1,358/1,358 TWSE and 891/891 TPEx rows on 2026-08-07
• foreign_available_pct must equal available / issued — TWSE floors it, TPEx rounds it; both matched 100% of rows

Left on by default, verifyWithIndustryTotals adds a second, independent check: the TWSE publishes a separate industry-level aggregate (MI_QFIIS_cat), and the Actor asserts that its own row set reconciles with it exactly — security count, issued shares and held shares all to the share. On 2026-08-07 that was 1,358 securities, 1,055,188,705,522 issued shares and 176,571,051,231 held, with zero difference.

Issued-share counts were separately cross-checked against the MOPS company filings feed (t187ap03_L): 1,018 of 1,093 matched exactly, with the remainder explained by ordinary reporting lag between the daily exchange report and the monthly company filing.

Input

Field	Type	Description
startDate	string (required)	YYYY-MM-DD. TWSE from 2004-02-11, TPEx from 2007-05-02
endDate	string	YYYY-MM-DD inclusive; empty = single day
market	string	both (default), twse, or tpex
stockCodes	array	Optional filter, e.g. ["2330", "5274"]. Empty = all (~2,250 securities/day)
minForeignHoldingPct	integer	Only return securities held at least this much by foreign investors. 0 = no filter
capRestrictedOnly	boolean	Only securities whose statutory cap is under 100% — the quota-squeeze universe
verifyWithIndustryTotals	boolean	Cross-check the latest session against the TWSE industry aggregate. Default true

Example — one month of foreign ownership for three tickers:

{
  "startDate": "2026-07-08",
  "endDate": "2026-08-07",
  "market": "both",
  "stockCodes": ["2330", "2317", "5274"]
}

Example — the quota-squeeze universe, one day:

{
  "startDate": "2026-08-07",
  "market": "both",
  "capRestrictedOnly": true
}

Pricing & cost control

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

• Full market (TWSE + TPEx), one day: ~2,250 records ≈ $1.12
• Filtered to 5 tickers, one month: ~110 records ≈ $0.06
• capRestrictedOnly: true, one day: ~29 records ≈ $0.02

For time-series work, filter by stockCodes — a year of daily history for a handful of tickers costs cents, while a year of the full market is 550,000+ records.

Data source & reliability

• Direct from the official TWSE MI_QFIIS and TPEx 僑外資及陸資持股比例排行表 feeds — no third-party intermediaries
• The TWSE renamed every column in 2009 when mainland investment was admitted (外資 → 外資及陸資, plus a new mainland-only cap). Columns are resolved by header name, so both layouts parse correctly and a future rename fails the run loudly instead of returning silently mis-mapped numbers
• TPEx echoes its latest published session for an out-of-range date; the Actor checks the echoed date and emits nothing rather than mislabelling it
• Weekends are skipped automatically; market holidays return no rows
• The exchanges refresh this report at 18:00 and 22:00 Taipei time; run after 22:00 for settled figures

Use cases

• Foreign ownership time series for any Taiwan ticker, for factor models and event studies
• Quota-squeeze screeners across regulated sectors — telecoms, aviation, shipping, broadcasting, defence
• Separating genuine foreign accumulation from GDR conversions and capital-increase artefacts
• Index and ETF research where foreign-availability caps affect investability weights
• Compliance and mandate monitoring against statutory foreign ownership ceilings

Related Actors

• TWSE Institutional Trades — the daily foreign/trust/dealer flow behind these ownership changes
• TPEx Institutional Trades — same for the OTC market
• Taiwan Short Sale & Securities Lending Balance — foreign institutional bear positioning
• Taiwan Shareholding Dispersion (TDCC) — weekly retail vs whale ownership
• Taiwan Margin Trading — retail leverage on the same securities
• Taiwan Dividend Calendar — ex-dividend dates and payouts

---

Taiwan Market Data Suite

This Actor is part of a suite of 19 Taiwan market data APIs by chamarix — official sources only, cross-validated against independent official endpoints, clean JSON out. Code samples for the whole suite: GitHub.

Market data:

• twse-institutional-trades — Daily institutional buy/sell (foreign, investment trust, dealer) per stock — TWSE listed
• tpex-institutional-trades — Daily institutional buy/sell per stock — TPEx OTC market
• taiwan-monthly-revenue — Monthly revenue of 1,900+ listed & OTC companies, MoM/YoY
• taiwan-financial-statements — Quarterly income statement, balance sheet & cash flow back to 2013
• taiwan-dividend-calendar — Ex-dividend / ex-rights dates, reference prices & payouts back to 2003
• taiwan-shareholder-meetings — Shareholder meeting dates, book closure periods, board elections & e-voting since 2005
• taiwan-emerging-stock-quotes — Emerging Stock Board (興櫃) quotes, pre-IPO company register & listing-application status
• taiwan-margin-trading — Daily margin trading & short sale balances per stock
• taiwan-sbl-short-sale-balance — Securities-lending short sale balances per stock
• taiwan-day-trading-stats — Day-trading volume, value & ratio per stock since 2014
• tdcc-shareholding-dispersion — Weekly TDCC shareholding dispersion (retail vs whale structure)
• taifex-institutional-derivatives — Institutional futures & options positions (TAIFEX), incl. put/call ratio
• taiwan-stock-alerts — Watch-list, disposition & short-sale suspension alerts
• taiwan-insider-share-transfers — Insider share-transfer filings (directors, officers, 10% holders) since 2002
• taiwan-director-shareholdings — Monthly director/officer shareholdings & share-pledge ratio since 1999
• taiwan-block-trades — Every block trade (鉅額交易) with price, size & basket constituents since 2005

Government & civic data:

• taiwan-legislator-monitor — Legislative Yuan bills, legislators & meetings
• taiwan-tender-monitor — Government e-procurement tenders (open calls, awards, failures)