---
reviewed_by:
  rd: Ronny
  pm:
---
# 台灣公司資料 API — `tw.openfun~api~company`

給 AI 閱讀的使用指引。人類可在 https://data.openfun.tw/datasets/tw.openfun~api~company 看到資料集說明。完整知識見 [knowledge.md](knowledge.md)。

---

## ⚠️ 開始之前（AI agent 必讀）

**Base URL**：`https://company.g0v.ronny.tw`
**認證**：不需要。此 API 完全公開，無需 Token 或帳號。
**授權標注**：使用此資料產出的內容需標注「資料來源：歐噴資料庫（data.openfun.tw）／經濟部商業發展署」

最簡查詢範例：
```bash
curl "https://company.g0v.ronny.tw/api/show/89285269"
```

禁止用 WebFetch 抓 HTML 頁面，請直接呼叫 API。

---

## 這份資料集能回答什麼問題

**可以回答：**
- 「統一編號 XXXXXXXX 是哪家公司或行號？」（查名稱、地址、負責人、資本額）
- 「這家公司的董事、監察人有哪些人？持股多少？」
- 「這家公司／行號還在營業嗎？」（查 `公司狀況` 或 `現況` 欄位）
- 「某某人是哪些公司或行號的負責人或董監事？」（依人名搜尋）
- 「某法人代表了哪些公司的董監事席位？」（依所代表法人搜尋）
- 「A 公司有幾家分公司？分公司的統編是多少？」（依母公司統編查分公司）
- 「某家公司歷次的名稱、地址或業務變更記錄」（加 `with_changelog=true`）
- 「某家公司最近是否有新增登記某個業別？」（分析 `所營事業資料` 變遷）

**無法回答：**
- 「財團法人、社團法人、政黨的登記資料」→ 請查 `tw.gov.judicial~ref~foundation`
- 「公司的營業稅籍資料（行業代碼、主要營業地址）」→ 請查 `tw.gov.fia.eip~ref~business-tax`
- 「公司實際資產、損益表、財務報表」→ 本 API 只有登記資料，不含財務資料
- 「某公司是否真的有從事某業務」→ 所營事業登記不精準，多數業別是公司自行勾選

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 經濟部商業發展署商工行政資料開放平台（[data.gov.tw/dataset/9400](https://data.gov.tw/dataset/9400)） |
| API 服務 | 由歐噴維護（company.g0v.ronny.tw） |
| 授權 | 政府資料開放授權條款－第1版 |
| 更新頻率 | 每日 |
| 涵蓋範圍 | 全台依《公司法》登記的公司，以及依《商業登記法》登記的行號（商號），含已廢止、撤銷者 |

---

## API 端點說明

### 端點 1：依統編查詢單一公司

```bash
# 基本查詢
curl "https://company.g0v.ronny.tw/api/show/89285269"

# 含歷次變更記錄
curl "https://company.g0v.ronny.tw/api/show/89285269?with_changelog=true"
```

**公司**（公司法）的主要回傳欄位：

| 欄位 | 說明 |
|------|------|
| `公司名稱` | 目前登記名稱（全國唯一） |
| `公司狀況` / `登記現況` | 如「核准設立」、「廢止」、「撤銷」 |
| `代表人姓名` | 公司負責人姓名 |
| `公司所在地` | 登記地址 |
| `資本總額(元)` | 登記資本額（新台幣） |
| `實收資本額(元)` | 已實際繳納資本（股份有限公司才有） |
| `核准設立日期` | 公司正式核准日期 |
| `所營事業資料` | 登記業務項目，格式為 `[["代碼", "業別名稱"], ...]` |
| `董監事名單` | 董事、監察人清單（含姓名、出資額、所代表法人） |
| `經理人名單` | 經理人清單（含姓名） |
| `財政部` | 財政部稅籍資料（含行業代碼、使用統一發票、營業地址） |
| `changelog` | 歷次變更紀錄（需加 `with_changelog=true`） |

**行號（商號）**（商業登記法）的主要回傳欄位：

| 欄位 | 說明 |
|------|------|
| `商業名稱` | 目前登記名稱（只在同縣市內唯一） |
| `現況` / `登記現況` | 如「核准設立」 |
| `負責人姓名` | 行號負責人姓名 |
| `地址` | 登記地址 |
| `資本額(元)` | 登記資本額 |
| `組織類型` | 「獨資」或「合夥」 |
| `出資額(元)` | 合夥人出資明細（合夥行號才有） |
| `核准設立日期` | 行號核准日期 |
| `營業項目` | 登記業務項目（文字格式，格式不一致） |
| `財政部` | 財政部稅籍資料 |

> **如何區分公司與行號**：回傳記錄含 `公司名稱` 欄位者為公司；含 `商業名稱` 者為行號。

---

### 端點 2：批量查詢多間公司

```bash
# 用分號分隔多個統編（最多可查多筆）
curl "https://company.g0v.ronny.tw/api/bulkquery?ids=89285269;24960372;70764274"
```

適合場景：已知一批統編，需要一次取得多家公司資料（如 KYC 盡職調查批量比對）。

---

### 端點 3：依公司名稱或地址搜尋

```bash
# 依名稱搜尋
curl "https://company.g0v.ronny.tw/api/search?q=台積電&page=1"

# 依地址搜尋（加 address: 前綴）
curl "https://company.g0v.ronny.tw/api/search?q=address:台北市信義區松仁路&page=1"

# 只查存續中的公司（排除已廢止、撤銷）
curl "https://company.g0v.ronny.tw/api/search?q=台積電&alive_only=true&page=1"
```

參數說明：

| 參數 | 說明 |
|------|------|
| `q` | 搜尋關鍵字（預設依名稱；加 `address:` 前綴則依地址） |
| `page` | 頁碼，從 1 開始 |
| `alive_only` | `true` 時只回傳狀況為「核准設立」的公司 |

回傳含 `found`（總筆數）與 `data`（當頁資料）。

---

### 端點 4：依董監事「所代表法人」搜尋

```bash
# 找以某法人名義出任董監事的所有公司
curl "https://company.g0v.ronny.tw/api/fund?q=國發基金&page=1"
```

適合場景：分析某法人（如政府基金、控股公司）在哪些公司持有董監事席位。

---

### 端點 5：依人名搜尋

```bash
# 依代表人、董監事或經理人的人名搜尋
curl "https://company.g0v.ronny.tw/api/name?q=張忠謀&page=1"
```

適合場景：查詢某人在哪些公司擔任負責人、董監事或經理人（自然人網絡分析）。

---

### 端點 6：依母公司統編查詢分公司

```bash
# 查某公司旗下所有分公司
curl "https://company.g0v.ronny.tw/api/branch?q=22099131&page=1"
```

適合場景：找出一家公司的所有分公司（`q` 帶母公司統編）。

---

## 分頁處理

`/api/search`、`/api/fund`、`/api/name`、`/api/branch` 均支援分頁。

```bash
# 第 2 頁
curl "https://company.g0v.ronny.tw/api/name?q=王大明&page=2"
```

回傳格式：
```json
{
  "found": 150,
  "data": [ ... ]
}
```

`found` 是總筆數，`data` 是當頁資料。

---

## 查詢範例

### 範例 1：KYC — 依統編查公司基本資料與董監事

```bash
# 步驟 1：查公司基本資料
curl "https://company.g0v.ronny.tw/api/show/89285269"

# 步驟 2：如需歷史變更（曾改名、遷址等）
curl "https://company.g0v.ronny.tw/api/show/89285269?with_changelog=true"
```

### 範例 2：自然人網絡分析

```bash
# 步驟 1：找此人擔任負責人/董監事/經理人的所有公司
curl "https://company.g0v.ronny.tw/api/name?q=某人姓名&page=1"

# 步驟 2：取得各公司統編後，逐一查詢詳情
curl "https://company.g0v.ronny.tw/api/show/{統編}"
```

### 範例 3：法人持股網絡分析

```bash
# 步驟 1：找此法人代表董監事的所有公司
curl "https://company.g0v.ronny.tw/api/fund?q=某法人名稱&page=1"

# 步驟 2：再用統編查各公司詳情
curl "https://company.g0v.ronny.tw/api/show/{統編}"
```

### 範例 4：批量統編對照公司名稱

```bash
# 一次查多個統編（分號分隔）
curl "https://company.g0v.ronny.tw/api/bulkquery?ids=89285269;24960372;70764274"
```

### 範例 5：找不到公司時的處理建議

1. **名稱搜尋無結果**：公司可能已改名，試試 `/api/search?q={舊名稱}` 或直接用統編查。若是行號，同名行號可能在不同縣市都有，搜尋結果可能有多筆。
2. **想確認是否仍在營業**：查 `公司狀況` 或 `現況` 欄位，「核准設立」表示存續中；或在搜尋時加 `alive_only=true`。
3. **公司名稱重複**：同一公司名稱在歷史上可能對應多個統編（前一家廢止後名稱被新公司再次使用）。用統編而非名稱作為識別依據。

---

## 注意事項與限制

1. **統編在公司存續期間穩定，但可能被重新配發**：改名、遷址、變更負責人都不影響統編，跨資料集 JOIN 應以統編為主鍵。但公司廢止後，該統編**可能在日後被重新配發給新公司或行號**。若歷史資料中某統編對應的公司名稱與 API 查到的不同，應警覺是否為統編重用。長期追蹤時應同時記錄公司名稱或設立日期輔助驗證。
2. **`公司名稱` 或 `商業名稱` 欄位只顯示目前登記名稱**：歷史名稱需加 `with_changelog=true` 取得變更紀錄。
3. **同時涵蓋公司與行號**：回傳記錄含 `公司名稱` 欄位者為公司（公司法），含 `商業名稱` 者為行號（商業登記法）。兩者欄位結構不同，請依欄位存在與否判斷類型。
4. **已廢止、撤銷者仍保留記錄**：若只需存續者，搜尋時加 `alive_only=true`，或查詢後過濾 `公司狀況`／`現況` 等於「核准設立」。
5. **公司名稱全國唯一，行號名稱只在同縣市唯一**：同一公司名稱在廢止後可被新公司再次使用，歷史上可能有同名不同統編的公司。行號同名則更常見（不同縣市可以有同名行號）。
6. **所營事業資料不精準**：除特許行業（旅行業、計程車業、典當業等）外，大部分業別是公司登記時自行勾選，不代表實際有在經營。`所營事業資料` 欄位僅供參考；**分析業務擴展**時，歷史變遷（何時新增某業別）比當前值更有意義。若需更精準的行業資訊，可參考 `tw.gov.fia.eip~ref~business-tax` 的行業代號（財政部稅籍，代表實際課稅的業別），但稅籍行業也是建立時填報，公司轉型後不一定更新。
7. **`所營事業資料` 格式不一致**：公司的 `所營事業資料` 通常是結構化陣列 `[["代碼", "業別名稱"], ...]`；行號的 `營業項目` 則格式混亂，舊記錄可能是純文字，新記錄可能含代碼但格式仍不統一。
8. **地址搜尋出現大量同地址公司 → 商務中心**：以 `address:` 搜尋時，若某地址下有大量公司登記，通常代表該地址為商務中心（公司掛名登記，實際辦公地點另在他處）。地址分析時需留意此現象，不可將登記地址等同於實際營業地點。

---

## 關聯資料集

| 資料集 | 關聯說明 |
|--------|---------|
| [`tw.gov.fia.eip~ref~business-tax`](../tw.gov.fia.eip~ref~business-tax/skill.md) | 同樣以統編為主鍵；涵蓋基金會等非公司非行號的營業人；含行業代碼、主要營業地址 |
| [`tw.gov.judicial~ref~foundation`](../tw.gov.judicial~ref~foundation/skill.md) | 財團法人、社團法人、政黨的法院登記資料（非公司、非行號） |

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Base URL | `https://company.g0v.ronny.tw` |
| 認證 | 不需要 |
| 依統編查單一公司 | `GET /api/show/{統編}` |
| 批量查詢 | `GET /api/bulkquery?ids={統編1};{統編2}` |
| 依名稱搜尋 | `GET /api/search?q={關鍵字}&alive_only=true` |
| 依地址搜尋 | `GET /api/search?q=address:{地址}` |
| 依所代表法人搜尋 | `GET /api/fund?q={法人名稱}` |
| 依人名搜尋 | `GET /api/name?q={姓名}` |
| 依母公司統編查分公司 | `GET /api/branch?q={母公司統編}` |
| 含歷史變更 | 在 `/api/show/{統編}` 加 `?with_changelog=true` |
| 分頁 | 加 `&page={N}`（從 1 開始）；回應含 `found` 總筆數 |
| 授權標注 | 資料來源：歐噴資料庫（data.openfun.tw）／經濟部商業發展署 |