# 大股東排行

`GET` `/v1/quote/shareholders/top`

獲取上市公司前 20 大股東（機構、個人、內部人）的持股數據，支持多報告期對比。`object_id` 可傳入 `shareholder_detail` 查看詳情。

## Parameters

### Query Parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `symbol` | string | Yes | 證券代碼，例如 `AAPL.US` |

## Request Example

```bash
curl --request GET \
  --url 'https://openapi.longbridge.com/v1/quote/shareholders/top?symbol=<symbol>' \
  --header 'Authorization: Bearer <access_token>'
```

## Response

### Response Properties

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `periods` | array | No | 可用報告期列表 |
| `info` | object[] | No | 各報告期的股東數據 |
| `└ period` | string | No | 報告期標籤（如 `Latest`） |
| `└ share_holders` | object[] | No | 股東列表（最多 20 條） |
| `└ ∟ object_id` | string | No | 股東唯一 ID，可傳入 `shareholder_detail` |
| `└ ∟ name` | string | No | 股東名稱 |
| `└ ∟ shares_held` | string | No | 持股數量 |
| `└ ∟ percent_shares_held` | string | No | 持股比例，含 `%` 符號（如 `9.71%`） |
| `└ ∟ shares_changed` | string | No | 持股變動數量（正增負減） |
| `└ ∟ percent_shares_changed` | string | No | 持股比例變動，含 `%` 符號 |
| `└ ∟ filing_date` | string | No | 申報日期 |
| `└ ∟ period` | string | No | 報告期標籤（如 `Latest`） |
| `└ ∟ title` | string | No | 股東類型（機構 / 個人 / 內部人） |

### Response JSON Example

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "info": [
      {
        "period": "Latest",
        "share_holders": [
          {
            "object_id": "148057",
            "name": "The Vanguard Group, Inc.",
            "title": "",
            "shares_held": "1426283914.00",
            "percent_shares_held": "9.71%",
            "percent_shares_changed": "0.01%",
            "shares_changed": "0.00",
            "period": "Latest",
            "filing_date": "2025/12/31"
          },
          {
            "object_id": "452583",
            "name": "BlackRock, Inc.",
            "title": "",
            "shares_held": "1138572603.00",
            "percent_shares_held": "7.75%",
            "percent_shares_changed": "-0.06%",
            "shares_changed": "-10565359.00",
            "period": "Latest",
            "filing_date": "2026/03/31"
          }
        ]
      }
    ]
  }
}
```
