Building an AI agent? Start with /llms.txt for the full site index.
Capital Flows
Shareholding distribution per stock by holding-size tier, sourced from the official TDCC shareholding-distribution table — holders and shares in each tier.
GET /v2/datasets/ownership-distributionownership-distribution returns one row per stock per holding-size tier per data date from the official TDCC shareholding-distribution table, showing how many holders and shares sit in each tier. It is published on a weekly cadence; each row carries its source role so a tier figure is traceable to the TDCC release.
| Field | Type | Description |
|---|---|---|
symbol | string | Ticker. |
data_date | string | Distribution reference date (weekly). |
holding_tier | string | Holding-size tier (share-count band). |
holders | number | Number of holders in the tier. |
shares | number | Shares held in the tier. |
source_role | string | Canonical source role (official_tdcc_shareholding_distribution). |
| Rows | 33,626 |
| Window | 2026-05-29 (single-day snapshot) |
| Grade | Verified |
A real response from this endpoint. Rows are returned under "data", and provenance is carried in the shape shown below — it is not identical across datasets, so read this page's rather than assuming another's.
{ "api_version": "v2", "endpoint": "/v2/datasets/ownership-distribution", "request_id": "req_375fb93dc782", "plan_id": "enterprise", "dataset": "ownership_distribution", "dataset_id": "ownership_distribution", "request_context": { "ticker": "2330", "as_of_date": "2026-05-29", "family": "chip_deep", "field_group_type": "derived", "dataset_view": "tdcc_v1_mapped_company_only_latest_snapshot", "known_gaps": [ "mapped_company_only_latest_snapshot", "latest_snapshot_only", "no_full_tdcc_universe_claim" ], "scope": "mapped-company-only", "coverage_type": "latest_snapshot", "dataset_id": "ownership_distribution", "report_date": "2026-05-29", "included_tickers": 1978, "excluded_tickers": 2004, "excluded_rows": 34068 }, "quality": { "freshness_state": "fresh", "freshness_as_of": "2026-05-29", "completeness_ratio": 1, "quality_status": "ready" }, "lineage": { "source_role": "canonical", "selected_source": "tdcc_shareholding_distribution_items", "fallback_chain": [], "policy_notes": [ "tdcc_v1_mapped_company_only_latest_snapshot", "contract-aligned filters: ticker/report_date/start_date/end_date/market/holder_bucket", "no_full_tdcc_coverage_claim" ] }, "error": { "error_code": null, "error_message": null, "dataset": "ownership_distribution", "request_id": "read-api-a653800fb418", "blocking_gate": null }, "data": [ { "security_identity": { "ticker": "2330", "market": "TWSE" }, "snapshot_context": { "report_date": "2026-05-29", "scope": "mapped-company-only", "coverage_type": "latest_snapshot" }, "distribution_bucket": { "holding_bucket": "TDCC_01", "holder_count": 2149965, "shares": 254881810, "holding_ratio": 0.0098 }, "source_lineage": { "source_provider": "tdcc_official", "source_role": "shareholding_distribution", "source_family": "dataset_1_5", "lineage": { "source_url": "https://smart.tdcc.com.tw/opendata/getOD.ashx?id=1-5", "report_date": "2026-05-29", "product_scope": "mapped_company_only_latest_snapshot_v1", "market_mapping_policy": "official_issuer_profile_union_only", "market_enrichment_sources": [ "https://openapi.twse.com.tw/v1/opendata/t187ap03_L", "https://www.tpex.org.tw/openapi/v1/mopsfin_t187ap03_O" ] } }, "data_gaps": [ "mapped_company_only_latest_snapshot", "excludes_etf_fund_preferred_emerging_unknown_unresolved", "not_full_tdcc_coverage" ], "safe_usage_notes": [ "latest_snapshot_only", "mapped_company_only_scope", "not_full_tdcc_coverage" ], "not_investment_advice": true, "available_tools_or_endpoints": { "dataset_endpoint": "/v2/datasets/ownership-distribution", "lookup_hint": "ticker=2330&market=TWSE", "scope_note": "tdcc_v1_mapped_company_only_latest_snapshot" } }, { "security_identity": { "ticker": "2330", "market": "TWSE" }, "snapshot_context": { "report_date": "2026-05-29", "scope": "mapped-company-only", "coverage_type": "latest_snapshot" }, "distribution_bucket": { "holding_bucket": "TDCC_02", "holder_count": 421963, "shares": 806563397, "holding_ratio": 0.0311 }, "source_lineage": { "source_provider": "tdcc_official", "source_role": "shareholding_distribution", "source_family": "dataset_1_5", "lineage": { "source_url": "https://smart.tdcc.com.tw/opendata/getOD.ashx?id=1-5", "report_date": "2026-05-29", "product_scope": "mapped_company_only_latest_snapshot_v1", "market_mapping_policy": "official_issuer_profile_union_only", "market_enrichment_sources": [ "https://openapi.twse.com.tw/v1/opendata/t187ap03_L", "https://www.tpex.org.tw/openapi/v1/mopsfin_t187ap03_O" ] } }, "data_gaps": [ "mapped_company_only_latest_snapshot", "excludes_etf_fund_preferred_emerging_unknown_unresolved", "not_full_tdcc_coverage" ], "safe_usage_notes": [ "latest_snapshot_only", "mapped_company_only_scope", "not_full_tdcc_coverage" ], "not_investment_advice": true, "available_tools_or_endpoints": { "dataset_endpoint": "/v2/datasets/ownership-distribution", "lookup_hint": "ticker=2330&market=TWSE", "scope_note": "tdcc_v1_mapped_company_only_latest_snapshot" } } ], "data_count": 17, "known_gaps": [ "mapped_company_only_latest_snapshot", "latest_snapshot_only", "no_full_tdcc_universe_claim" ], "data_gaps": [ "mapped_company_only_latest_snapshot", "latest_snapshot_only", "no_full_tdcc_universe_claim" ], "query": { "symbol": "2330", "report_date": null, "as_of_date": null, "start_date": null, "end_date": null, "market": null, "holder_bucket": null, "limit": 50, "legacy_aliases_used": { "ticker": false, "date_from": false, "date_to": false, "bucket": false, "offset": false, "sort_by": false, "sort_order": false } }, "meta": { "rows_returned": 17, "mandatory_contract_fields_present": [ "api_version", "data", "data_as_of" ], "plan": "enterprise", "row_limit": 100000, "is_limited": false }, "envelope": { "api_version": "v2", "dataset": "ownership_distribution", "dataset_version": "v2.0.0-preview", "release_version": "v2.2026-05-29.preview", "release_date": "2026-05-29", "data_as_of": "2026-05-29", "request_context": { "ticker": "2330", "as_of_date": "2026-05-29", "family": "chip_deep", "field_group_type": "derived", "dataset_view": "tdcc_v1_mapped_company_only_latest_snapshot", "known_gaps": [ "mapped_company_only_latest_snapshot", "latest_snapshot_only", "no_full_tdcc_universe_claim" ], "scope": "mapped-company-only", "coverage_type": "latest_snapshot", "dataset_id": "ownership_distribution", "report_date": "2026-05-29", "included_tickers": 1978, "excluded_tickers": 2004, "excluded_rows": 34068 }, "data": [ { "security_identity": { "ticker": "2330", "market": "TWSE" }, "snapshot_context": { "report_date": "2026-05-29", "scope": "mapped-company-only", "coverage_type": "latest_snapshot" }, "distribution_bucket": { "holding_bucket": "TDCC_01", "holder_count": 2149965, "shares": 254881810, "holding_ratio": 0.0098 }, "source_lineage": { "source_provider": "tdcc_official", "source_role": "shareholding_distribution", "source_family": "dataset_1_5", "lineage": { "source_url": "https://smart.tdcc.com.tw/opendata/getOD.ashx?id=1-5", "report_date": "2026-05-29", "product_scope": "mapped_company_only_latest_snapshot_v1", "market_mapping_policy": "official_issuer_profile_union_only", "market_enrichment_sources": [ "https://openapi.twse.com.tw/v1/opendata/t187ap03_L", "https://www.tpex.org.tw/openapi/v1/mopsfin_t187ap03_O" ] } }, "data_gaps": [ "mapped_company_only_latest_snapshot", "excludes_etf_fund_preferred_emerging_unknown_unresolved", "not_full_tdcc_coverage" ], "safe_usage_notes": [ "latest_snapshot_only", "mapped_company_only_scope", "not_full_tdcc_coverage" ], "not_investment_advice": true, "available_tools_or_endpoints": { "dataset_endpoint": "/v2/datasets/ownership-distribution", "lookup_hint": "ticker=2330&market=TWSE", "scope_note": "tdcc_v1_mapped_company_only_latest_snapshot" } }, { "security_identity": { "ticker": "2330", "market": "TWSE" }, "snapshot_context": { "report_date": "2026-05-29", "scope": "mapped-company-only", "coverage_type": "latest_snapshot" }, "distribution_bucket": { "holding_bucket": "TDCC_02", "holder_count": 421963, "shares": 806563397, "holding_ratio": 0.0311 }, "source_lineage": { "source_provider": "tdcc_official", "source_role": "shareholding_distribution", "source_family": "dataset_1_5", "lineage": { "source_url": "https://smart.tdcc.com.tw/opendata/getOD.ashx?id=1-5", "report_date": "2026-05-29", "product_scope": "mapped_company_only_latest_snapshot_v1", "market_mapping_policy": "official_issuer_profile_union_only", "market_enrichment_sources": [ "https://openapi.twse.com.tw/v1/opendata/t187ap03_L", "https://www.tpex.org.tw/openapi/v1/mopsfin_t187ap03_O" ] } }, "data_gaps": [ "mapped_company_only_latest_snapshot", "excludes_etf_fund_preferred_emerging_unknown_unresolved", "not_full_tdcc_coverage" ], "safe_usage_notes": [ "latest_snapshot_only", "mapped_company_only_scope", "not_full_tdcc_coverage" ], "not_investment_advice": true, "available_tools_or_endpoints": { "dataset_endpoint": "/v2/datasets/ownership-distribution", "lookup_hint": "ticker=2330&market=TWSE", "scope_note": "tdcc_v1_mapped_company_only_latest_snapshot" } } ], "quality": { "freshness_state": "fresh", "freshness_as_of": "2026-05-29", "completeness_ratio": 1, "quality_status": "ready" }, "lineage": { "source_role": "canonical", "selected_source": "tdcc_shareholding_distribution_items", "fallback_chain": [], "policy_notes": [ "tdcc_v1_mapped_company_only_latest_snapshot", "contract-aligned filters: ticker/report_date/start_date/end_date/market/holder_bucket", "no_full_tdcc_coverage_claim" ] }, "error": { "error_code": null, "error_message": null, "dataset": "ownership_distribution", "request_id": "read-api-a653800fb418", "blocking_gate": null }, "dataset_id": "ownership_distribution", "dataset_label_zh": "<Chinese value - see the zh page>", "dataset_label_en": "TDCC Shareholding Distribution", "report_date": "2026-05-29", "scope": "mapped-company-only", "coverage_type": "latest_snapshot", "row_count": 17, "included_tickers": 1978, "excluded_tickers": 2004, "excluded_rows": 34068, "known_gaps": [ "mapped_company_only_latest_snapshot", "latest_snapshot_only", "no_full_tdcc_universe_claim" ] }}Captured from the live API on 2026-07-20.
Chinese data values are shown as a marker here so this page stays in English; the /zh page shows them verbatim.
curl "https://api.twmarketdata.com/v2/datasets/ownership-distribution?ticker=2330" \ -H "X-API-Key: sk_live_..."| Parameter | Required | Type | Description |
|---|---|---|---|
symbol | Yes | string | Ticker, e.g. 2330. |
start_date | No | string (YYYY-MM-DD) | Start of the query range. |
end_date | No | string (YYYY-MM-DD) | End of the query range. |
limit | No | integer | Maximum rows to return. |
A first call:
import requests resp = requests.get( "https://api.twmarketdata.com/v2/datasets/ownership-distribution", params={"ticker": "2330"}, headers={"X-API-Key": "sk_live_..."},)resp.raise_for_status()print(resp.json()["data"])With a date-range filter:
import requests # The full verified example — the same call with every supported filter set.resp = requests.get( "https://api.twmarketdata.com/v2/datasets/ownership-distribution", params={"ticker": "2330"}, headers={"X-API-Key": "sk_live_..."},)resp.raise_for_status()for row in resp.json()["data"]: print(row)This endpoint is GET /v2/datasets/ownership-distribution. The full machine-readable schema (parameters, security, response envelope) lives in the OpenAPI spec.