# Taiwan Shareholding Dispersion (TDCC 集保戶股權分散表) (`chamarix/tdcc-shareholding-dispersion`) Actor

Weekly shareholding dispersion for 4,000+ Taiwan securities from official TDCC data. Retail vs whale ownership across 15 holding tiers, >400-lot big-holder ratio, up to 52 weeks of per-stock history. The go-to chip-analysis (籌碼分析) dataset.

- **URL**: https://apify.com/chamarix/tdcc-shareholding-dispersion.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 Shareholding Dispersion (TDCC 集保戶股權分散表)

Get structured JSON access to the **weekly shareholding dispersion table from TDCC** (Taiwan Depository & Clearing Corporation) — the definitive dataset for Taiwan **chip analysis (籌碼分析)**: who owns each stock, from odd-lot retail to 1,000+ lot whales.

Every week TDCC publishes, for every Taiwan security, the number of shareholders and shares held across 15 holding-size tiers. This Actor normalizes that into one JSON record per stock per week, with the famous **>400-lot big-holder ratio (大戶持股比)** pre-computed.

### Why this data matters

- **大戶持股比 (>400-lot holder %)** is one of the most-watched ownership signals in Taiwan — rising whale concentration with falling retail count is a classic accumulation pattern
- **Retail holder count** (level 1: 1-999 shares) tracks odd-lot retail crowding, a contrarian indicator
- Weekly frequency sits perfectly between daily institutional flows and quarterly filings
- Used by virtually every Taiwan chip-analysis platform — now you can pipe the raw official data into your own models

### Output

One record per security per weekly snapshot. Key fields:

```json
{
  "date": "2026-07-24",
  "stock_code": "2330",
  "total_holders": 3041119,
  "total_shares": 25932370067,
  "large_holders": 2618,
  "large_shares": 22690712233,
  "large_pct": 87.48,
  "level_01_holders": 2486327,
  "level_01_shares": 288004489,
  "level_01_pct": 1.11,
  "level_15_holders": 1472,
  "level_15_shares": 21966501280,
  "level_15_pct": 84.7,
  "diff_adjustment_shares": 0
}
```

Each of the 15 tiers has `_holders`, `_shares`, `_pct` fields (45 tier fields total). Tier definitions (shares held):

| Level | Range | Level | Range |
|---|---|---|---|
| 1 | 1-999 | 9 | 50,001-100,000 |
| 2 | 1,000-5,000 | 10 | 100,001-200,000 |
| 3 | 5,001-10,000 | 11 | 200,001-400,000 |
| 4 | 10,001-15,000 | 12 | 400,001-600,000 |
| 5 | 15,001-20,000 | 13 | 600,001-800,000 |
| 6 | 20,001-30,000 | 14 | 800,001-1,000,000 |
| 7 | 30,001-40,000 | 15 | 1,000,001+ |
| 8 | 40,001-50,000 | | |

`large_*` = sum of levels 12-15 (>400,000 shares = >400 lots, the standard 大戶 threshold). `diff_adjustment_shares` is TDCC's reconciliation row, normalized so that `total_shares = Σ level shares + diff_adjustment_shares`.

### Input

| Field | Type | Description |
|---|---|---|
| `stockCodes` | array | Optional filter, e.g. `["2330", "2317"]`. Empty = all ~4,000 securities (latest week only) |
| `weeks` | integer | Weekly snapshots to fetch, 1-52 (default 1). `weeks > 1` requires `stockCodes` |

**Full-market snapshot** (latest week, ~4,000 securities):

```json
{ "stockCodes": [], "weeks": 1 }
```

**One year of history for a watchlist**:

```json
{ "stockCodes": ["2330", "2454", "5274"], "weeks": 52 }
```

Historical mode is capped at `stocks × weeks ≤ 600` per run to keep polite request pacing; split larger backfills across runs.

### Pricing & cost control

Pay per result: **$0.50 / 1,000 records** (one record = one stock-week).

- Full market, latest week: ~4,000 records ≈ $2.00
- 10 tickers × 52 weeks: 520 records ≈ $0.26

### Data source & reliability

- Direct from TDCC's official open-data feed (full-market snapshot) and TDCC's official per-stock query service (history, ~12 months available)
- Both endpoints cross-validated against each other — identical numbers for the same stock/week
- Share-count reconciliation identity is verified for every record at parse time; schema drift fails loudly instead of returning silently corrupted data
- New snapshots publish weekly (data date = last business day of the week)

### Use cases

- 大戶/散戶 ownership trend screeners and alerts
- Whale accumulation detection combined with [institutional flows](https://apify.com/chamarix/twse-institutional-trades)
- Retail crowding contrarian indicators
- Ownership-concentration factor research and backtesting
- Financial dashboards, newsletters, and stock-picking tools

### Related Actors

- [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
- [Taiwan Margin Trading Balance](https://apify.com/chamarix/taiwan-margin-trading) — daily margin & short selling balances
- [Taiwan Monthly Revenue](https://apify.com/chamarix/taiwan-monthly-revenue) — monthly revenue of all listed companies

# Actor input Schema

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

Optional list of stock codes (e.g., \['2330', '2317']). Leave empty to get ALL ~4,000 securities (latest week only). Required when weeks > 1.

## `weeks` (type: `integer`):

How many recent weekly snapshots to fetch (1-52). weeks=1 uses the full-market open data feed. weeks>1 fetches per-stock history and requires stockCodes (max stocks × weeks = 600).

## Actor input object example

```json
{
  "stockCodes": [
    "2330",
    "2317",
    "2454"
  ],
  "weeks": 1
}
```

# 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 = {
    "stockCodes": [
        "2330",
        "2317",
        "2454"
    ],
    "weeks": 1
};

// Run the Actor and wait for it to finish
const run = await client.actor("chamarix/tdcc-shareholding-dispersion").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 = {
    "stockCodes": [
        "2330",
        "2317",
        "2454",
    ],
    "weeks": 1,
}

# Run the Actor and wait for it to finish
run = client.actor("chamarix/tdcc-shareholding-dispersion").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 '{
  "stockCodes": [
    "2330",
    "2317",
    "2454"
  ],
  "weeks": 1
}' |
apify call chamarix/tdcc-shareholding-dispersion --silent --output-dataset

```

## MCP server setup

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

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/ImCa770MLZud4NmUX/builds/Ss16kDncKJfPxemAx/openapi.json