Com APItdcc.com.tw ↗
Access TDCC shareholder distribution, custody statistics, and security metadata for Taiwan-listed stocks via 7 structured endpoints.
What is the Com API?
The TDCC API exposes 7 endpoints covering shareholder distribution brackets, bulk custody statistics, and security metadata sourced from the Taiwan Depository & Clearing Corporation. The get_shareholder_distribution endpoint returns per-bracket holder counts and share volumes for any listed stock by numeric ID and date, while get_security_basic_info delivers exchange-wide security attributes across listed, OTC, and emerging markets.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/7737d49f-5a36-4798-bca8-a07a89dcdc96/get_available_dates' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace tdcc-com-tw-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.taiwan_tdcc_financial_data_api import TDCC, Stock, MarketType
client = TDCC()
# Get available shareholder distribution dates
for date in client.stocks.available_dates(limit=5):
print(date)
# Search for stocks by Chinese name
for name in client.stocks.search_by_name(query="台積電"):
print(name)
# Construct a stock and get its shareholder distribution
tsmc = client.stock(id="2330")
for bracket in tsmc.distribution.list(date="20260605"):
print(bracket.level, bracket.holders, bracket.shares, bracket.percentage)
# List all securities
for security in client.securities.list(limit=5):
print(security.code, security.name, security.market, security.par_value)
# Get bulk holdings data
for holding in client.holdings.list(limit=10):
print(holding.stock_code, holding.bracket_level, holding.holders, holding.shares)
# Get monthly custody records for listed market
for record in client.custodies.list(market_type=MarketType.LISTED, limit=10):
print(record.stock_code, record.stock_name, record.change_amount, record.change_percentage)
# Fetch a raw open dataset
dataset = client.datasets.fetch(data_id="1-5")
print(dataset.data[0])
Retrieve the list of available data dates in YYYYMMDD format for the shareholder distribution query. Returns weekly dates going back approximately one year, ordered newest first.
No input parameters required.
{
"type": "object",
"fields": {
"dates": "array of date strings in YYYYMMDD format, ordered newest first"
},
"sample": {
"data": {
"dates": [
"20260605",
"20260529",
"20260522"
]
},
"status": "success"
}
}About the Com API
Shareholder Distribution Data
The core get_shareholder_distribution endpoint accepts a stock_id (e.g. '2330' for TSMC) and an optional date in YYYYMMDD format. The response includes an array of bracket objects with fields for bracket label (持股/單位數分級), holder count (人數), share volume (股數/單位數), and percentage of total TDCC-held shares (占集保庫存數比例 (%)). The get_available_dates endpoint returns the full list of available weekly dates, ordered newest first, so you can iterate over historical snapshots going back roughly one year.
Bulk and Open Data Endpoints
get_bulk_shareholder_distribution fetches the full cross-stock shareholder distribution dataset in one call — fields include 資料日期, 證券代號, 持股分級, 人數, 股數, and 占集保庫存數比例%. Expect response times of 10–15 seconds. get_security_basic_info retrieves basic attributes for all securities (listed, OTC, emerging), including 證券代號, 證券名稱, 市場別, 發行幣別, 每股面額(元), and 證券狀態. Both are convenience wrappers around get_open_data, which accepts a data_id string (e.g. '1-1', '1-5', '2-22') for direct access to other TDCC Open Data datasets.
Custody and Search Endpoints
get_securities_custody_individual_monthly returns month-over-month custody change data per security, including 本月底保管千股數, 前月底保管千股數, 增減數額, 增減百分比, and 集保股東戶數. Dates use ROC calendar format (e.g. 11503 = March 2026). The optional market_type parameter filters results to 'listed', 'otc', or 'emerging'. To find a stock's numeric ID, search_stock_by_name accepts a Chinese name or partial name (e.g. '台積電') and returns matching name suggestions — numeric ID queries return empty results.
The Com API is a managed, monitored endpoint for tdcc.com.tw — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when tdcc.com.tw changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official tdcc.com.tw API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track weekly changes in TSMC shareholder bracket counts using
get_shareholder_distributionwith successive dates fromget_available_dates. - Screen for securities where small retail holders (low bracket) are growing as a share of total custody volume.
- Build a cross-stock ownership concentration index using bulk bracket data from
get_bulk_shareholder_distribution. - Monitor month-over-month custody share changes for OTC-market stocks via
get_securities_custody_individual_monthlywithmarket_type='otc'. - Resolve Chinese company names to numeric stock IDs using
search_stock_by_namebefore querying distribution data. - Audit security status fields (
證券狀態,停止過戶領回) across all listed instruments viaget_security_basic_info. - Pull arbitrary TDCC Open Data datasets not covered by named endpoints using
get_open_datawith a knowndata_id.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TDCC provide an official developer API?+
What does `get_shareholder_distribution` return and how granular are the brackets?+
How fresh is the shareholder distribution data?+
get_available_dates endpoint shows the actual dates available, going back approximately one year. There is no intraday or daily update frequency — the data is as fresh as TDCC's weekly publication cycle.Does the API cover foreign-listed or ADR data for Taiwanese companies?+
Can I filter `get_shareholder_distribution` results to a specific bracket range?+
get_bulk_shareholder_distribution endpoint similarly returns all brackets for all stocks in one payload. You can fork the API on Parse and revise it to add a bracket-filter parameter if needed.