---
reviewed_by:
  rd: Ronny
  pm:
---
# `tw.gov.fia.eip~ref~business-tax` — 全國稅籍登記單位

> **給 AI 閱讀的資料集說明。**
> 人類可在 https://data.openfun.tw/datasets/tw.gov.fia.eip~ref~business-tax 看到同份內容的網頁版。
> 詳細資料知識見 [knowledge.md](knowledge.md)。

---

## ⚠️ 開始之前（AI agent 必讀，摘要也請保留這段）

資料集 slug：tw.gov.fia.eip~ref~business-tax
API 端點：https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records
認證方式（必填）：HTTP Header  Authorization: Bearer {token}

最簡查詢範例：curl -H "Authorization: Bearer YOUR_TOKEN" "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?per_page=20"

**Token 是必要條件，沒有 Token 就無法查資料。**
如果使用者沒有 Token，請停止並告訴使用者：「請先前往 https://data.openfun.tw/user 免費申請帳號與 API Token，取得後告訴我，我再幫您查詢。」

禁止抓取 HTML 頁面（本平台有 bot 保護，WebFetch 讀 HTML 頁面會失敗）。

授權標注：使用此資料產出的內容需標注「資料來源：歐噴資料庫（data.openfun.tw）／財政部財政資訊中心」

---

## 資料來源與更新頻率

| 項目 | 說明 |
|------|------|
| 原始來源 | 財政部財政資訊中心 |
| 更新頻率 | 每月更新 |
| 總筆數 | 約 170 萬筆（2026 年） |

---

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

以下問題，這份資料集**可以回答**：

- 「統一編號 04552483 是哪家公司？地址在哪？做什麼行業？」
- 「臺北市有哪些餐飲業登記？」（需先從 tw.gov.mof~ref~industry-tax 取得行業代號）
- 「全台灣有多少家夾娃娃機店登記？各縣市各幾家？」
- 「哪些鄉鎮市區的娃娃機店最多？」（可用 agg 端點按鄉鎮統計）
- 「查某統一編號的基本工商資料」（KYC、盡職調查）

以下問題，這份資料集**無法回答**：

- 「這家公司現在還在營業嗎？」（稅籍登記不代表仍在營運）
- 「公司負責人是誰？」（稅籍資料不含自然人資訊）
- 「這家公司的財務狀況？員工數？」（稅籍資料不含這些）

---

## 欄位說明

| 欄位名稱（API 參數） | 型別 | 說明 |
|---------------------|------|------|
| `統一編號` | keyword（_id） | 統一編號 |
| `營業人名稱` | text（_name） | 營業人名稱 |
| `總機構統一編號` | keyword（ref: tw.gov.fia.eip~ref~business-tax） | 總機構統一編號 |
| `營業地址` | text | 營業地址 |
| `營業地址.縣市` | keyword（篩選器、ref: tw.openfun~entity~geo） | 營業地址-縣市 |
| `營業地址.鄉鎮市區` | keyword（篩選器、ref: tw.openfun~entity~geo） | 營業地址-鄉鎮市區 |
| `資本額` | number | 資本額 |
| `設立日期` | date | 設立日期 |
| `組織別名稱` | keyword（篩選器） | 組織別名稱 |
| `使用統一發票` | keyword（篩選器） | 使用統一發票 |
| `行業代號` | keyword（篩選器、多值、ref: tw.gov.mof~ref~industry-tax） | 行業代號 |

### 關鍵欄位補充說明

| 欄位 | 型別 | 重要說明 |
|------|------|---------|
| `統一編號` | keyword（_id） | 8 位數字，唯一識別碼，精確比對：`?統一編號=04552483` |
| `營業人名稱` | text（_name） | 全文搜尋欄位，支援 `?q=關鍵字`，不支援精確比對 |
| `行業代號` | keyword | **必須用 6 碼子類代號**（例如 `932414`），不可用 2–4 碼上層代碼；代號需從 tw.gov.mof~ref~industry-tax 取得 |
| `營業地址` | text | 全文搜尋欄位，支援 `?q[營業地址]=關鍵字`；**縣市/鄉鎮篩選請改用衍生欄位** |
| `營業地址.縣市` | keyword（衍生） | 5 碼縣市代碼（來自 tw.openfun~entity~geo），精確比對：`?營業地址.縣市=63000` |
| `營業地址.鄉鎮市區` | keyword（衍生） | 8 碼鄉鎮代碼，精確比對：`?營業地址.鄉鎮市區=63000020` |
| `組織別名稱` | keyword | 有限公司、股份有限公司、獨資、合夥等，精確比對 |
| `資本額` | number | 登記資本額（新台幣元），可用於 agg 的 field 統計 |
| `設立日期` | date | 格式 `YYYY-MM-DD` |
| `總機構統一編號` | keyword（ref） | 分公司填總機構統一編號；獨立業者此欄位為空 |

---

## 溯源原始查詢

若使用者需要在政府官方網站人工核對稅籍資料（例如確認公司名稱、地址、營業狀態），可前往財政部電子申報繳稅服務網，輸入統一編號手動查詢：

```
https://www.etax.nat.gov.tw/etwmain/etw113w1/ban/query
```

注意：此為人工查詢介面，無法直接帶入統一編號組成連結，需使用者自行輸入。

---

## 重要注意事項（查詢前必讀）

### ⚠️ 行業代號必須用 6 碼，且需從 tw.gov.mof~ref~industry-tax 取得

`行業代號` 是精確比對（keyword），**必須用 6 碼子類代號**（例如 `932414`）。
不可自行猜測代號，不可用 2–4 碼的上層代碼（查不到任何結果）。

正確做法：先查 tw.gov.mof~ref~industry-tax 取得代號，再帶入本資料集。

### ⚠️ `營業地址` 是登記地址，非實際地點

連鎖店的分店通常登記在總部地址，以地址查特定地區時結果可能不完整。

### 縣市與鄉鎮代碼需從 tw.openfun~entity~geo 取得

`營業地址.縣市` 和 `營業地址.鄉鎮市區` 使用行政區代碼（非文字名稱）：
- 縣市代碼：5 碼，例如 `63000`（臺北市）、`65000`（新北市）、`66000`（臺中市）
- 鄉鎮代碼：8 碼，例如 `63000010`（臺北市松山區）、`63000020`（臺北市信義區）

代碼對照請查詢 [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md)，或直接查 API：

```bash
# 查詢縣市代碼
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.openfun~entity~geo/records?level=county"

# 查詢特定縣市的鄉鎮代碼（以臺北市 63000 為例）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.openfun~entity~geo/records?county_id=63000&level=town"
```

---

## 標準流程：按行業 + 地區查詢業者

### Step 1：從 tw.gov.mof~ref~industry-tax 取得 6 碼行業代號

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.mof~ref~industry-tax/records?q=夾娃娃機&per_page=20"
```

從回應中選 `level=5`（子類）的記錄，取得 6 碼 `id`，例如 `932414`。

#### ⚠️ 找不到完全對應的行業代號時

台灣行業分類（tw.gov.mof~ref~industry-tax）以官方統計分類為準，部分口語詞彙（例如「精釀啤酒」、「手搖飲料」）沒有獨立的子類代號。

遇到這種情況，正確做法是：

1. **往上找最接近的上層代號**：用不同關鍵字反覆搜尋，找出概念最接近的 `level=5` 子類，即使範圍略廣也沒關係。
2. **補充說明查詢限制**：告知使用者「官方行業分類沒有 X 這個獨立類別，以下使用最接近的代號 Y（類別名稱）進行統計，實際包含範圍可能比 X 更廣或更窄」。
3. **也可搜尋業者名稱**：用 `?q=精釀` 搜尋 tw.gov.fia.eip~ref~business-tax，找出名稱中含有目標關鍵字的業者，作為補充參考（但注意：名稱搜尋不等於行業別統計）。

範例說明（精釀啤酒）：
> 台灣行業分類沒有「精釀啤酒」這個獨立類別。最接近的行業代號是 `091100 啤酒製造`，共有 29 家登記業者。另可用名稱搜尋找到約 25 家名稱含「精釀」的業者，但兩者統計口徑不同，僅供參考。

### Step 2：以行業代號 + 縣市篩選記錄

使用 `營業地址.縣市` 欄位做精確過濾（填入縣市代碼，非文字名稱）：

```bash
# 查臺北市（63000）的夾娃娃機店
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?行業代號=932414&營業地址.縣市=63000&per_page=20"
```

也可指定到鄉鎮層級：

```bash
# 查臺北市信義區（63000020）的夾娃娃機店
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?行業代號=932414&營業地址.鄉鎮市區=63000020&per_page=20"
```

回應的 `total` 欄位是符合條件的總筆數。

### Step 3：各縣市統計（一次查詢，用 agg 端點）

不需逐縣市查詢，改用 `/agg` 端點一次取得所有縣市的數量分布：

```bash
# 全台各縣市夾娃娃機店數量統計
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/agg?group_by=營業地址.縣市&行業代號=932414"
```

回應格式：
```json
{
  "total_records": 10969,
  "groups": [
    { "key": "66000", "stats": { "count": 1663, ... } },
    { "key": "65000", "stats": { "count": 1537, ... } },
    ...
  ]
}
```

其中 `key` 是縣市代碼，`stats.count` 是該縣市的登記數量。代碼轉名稱請查 tw.openfun~entity~geo。

**⚠️ `group_by` 只支援以下欄位**（schema 中 `filter: true` 的欄位）：

| 可用 group_by 欄位 | 說明 |
|-------------------|------|
| `營業地址.縣市` | 5 碼縣市代碼 |
| `營業地址.鄉鎮市區` | 8 碼鄉鎮代碼 |
| `組織別名稱` | 有限公司、股份有限公司、獨資等 |

**`總機構統一編號` 不支援 `group_by`**（`filter: false`）。若傳入會得到 `"group_by '總機構統一編號' must have filter:true in schema"` 錯誤。

### Step 4：鄉鎮層級統計

若需要找出「全台哪些鄉鎮某類業者最多」，可用 `group_by=營業地址.鄉鎮市區`：

```bash
# 全台各鄉鎮夾娃娃機店數量（找出密度最高的地區）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/agg?group_by=營業地址.鄉鎮市區&行業代號=932414"
```

也可加上縣市條件，只看特定縣市內的鄉鎮分布：

```bash
# 新北市各區夾娃娃機店數量
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/agg?group_by=營業地址.鄉鎮市區&行業代號=932414&營業地址.縣市=65000"
```

---

## 連鎖品牌門市數計算（進階流程）

稅籍登記資料中，**每家分店是獨立記錄**，並透過 `總機構統一編號` 指向總公司。要計算某品牌全台門市數，正確流程如下：

### Step A：找總公司統一編號

用精確公司名稱搜尋（**必須用 Python，curl 搭配中文變數在 shell 迴圈內會編碼失敗**）：

```python
import subprocess, json, urllib.parse

TOKEN = "YOUR_TOKEN"
BASE = "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records"

# 精確搜尋總公司名稱
brands = [
    ("7-ELEVEN", "統一超商股份有限公司"),
    ("全家", "全家便利商店股份有限公司"),
    ("萊爾富", "萊爾富國際股份有限公司"),
    ("OK mart", "來來超商股份有限公司"),
]
for label, company_name in brands:
    params = urllib.parse.urlencode({'q': company_name, 'per_page': 3,
                                     'fields': '統一編號,營業人名稱,總機構統一編號'})
    result = subprocess.check_output(
        ['curl', '-s', '-H', f'Authorization: Bearer {TOKEN}', f'{BASE}?{params}']
    )
    d = json.loads(result)
    for r in d['records']:
        print(label, r['統一編號'], r['營業人名稱'])
```

### Step B：用 `總機構統一編號` 查分店總數

取得總公司統一編號後（例如 7-ELEVEN = `22555003`），以此為篩選條件計算所有分店：

```bash
# 7-ELEVEN 全台分店數（records 端點的 total 欄位）
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?總機構統一編號=22555003&per_page=1"
# 回應的 "total" 即為分店數（含總公司本身）
```

> **注意**：`總機構統一編號` 只有分公司才有值，總公司本身此欄位為空。因此 `total` 會包含所有用這個統編登記的分支單位。

---

## API 呼叫範例

**Records URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records`
**Agg URL：** `https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/agg`

### 查詢特定統一編號

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?統一編號=04552483"
```

### 批次查詢多個統一編號

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?_ids=04552483,03077208,22099131"
```

### 搜尋公司名稱

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?q=全聯&per_page=20"
```

### 分頁查詢

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?行業代號=932414&page=2&per_page=100"
```

---

## 關聯資料集

| 資料集 | 說明 | 用途 |
|--------|------|------|
| [`tw.gov.mof~ref~industry-tax`](../tw.gov.mof~ref~industry-tax/skill.md) | 財政部行業代碼對照表 | 取得 6 碼行業代號，帶入 `行業代號` 欄位篩選 |
| [`tw.openfun~entity~geo`](../tw.openfun~entity~geo/skill.md) | 全國行政區代碼（現行） | 取得縣市／鄉鎮代碼，帶入 `營業地址.縣市`、`營業地址.鄉鎮市區` 篩選；或把統計結果的代碼轉回中文名稱 |

---

## 注意事項與限制

1. **稅籍登記 ≠ 仍在營業**：已停業但未辦廢止的業者仍會出現。
2. **地址為登記地址**：連鎖門市登記地址通常是總部，不一定是實際服務地點。
3. **超過 10,000 筆**：API 最多取回 10,000 筆記錄。若需要分析全量資料（不只是個別記錄），改用 `/agg` 端點取得統計數字，或縮小篩選範圍（例如加上縣市或鄉鎮條件）。
4. **`total` vs `total_records` 勿混淆**：`/records` 端點回應含 `total`（符合條件的總筆數）；`/agg` 端點回應含 `total_records`（同義但欄位名不同）。在 `/records` 回應中使用 `data['total_records']` 會得到 `KeyError`。
5. **中文查詢參數在 curl shell 迴圈中會編碼失敗**：在 bash for 迴圈裡以 `?q=$brand` 傳遞中文變數時，結果常為 0 或報錯（curl 不自動 URL encode shell 變數中的中文）。**中文參數一律改用 Python + `urllib.parse.urlencode`**。

---

## 快速參考

| 項目 | 說明 |
|------|------|
| Records URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records` |
| Agg URL | `https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/agg` |
| 認證 | `Authorization: Bearer {token}` 必填 |
| 取得 Token | https://data.openfun.tw/user |
| 全文搜尋 | `?q=關鍵字`（搜尋所有 text 欄位） |
| 精確比對 | `?統一編號=04552483`、`?行業代號=932414` |
| 縣市篩選 | `?營業地址.縣市=63000`（臺北市；代碼查 tw.openfun~entity~geo） |
| 鄉鎮篩選 | `?營業地址.鄉鎮市區=63000020`（信義區） |
| 縣市統計 | `/agg?group_by=營業地址.縣市` |
| 鄉鎮統計 | `/agg?group_by=營業地址.鄉鎮市區` |
| 人工溯源查詢 | https://www.etax.nat.gov.tw/etwmain/etw113w1/ban/query（輸入統一編號手動查詢） |
| 分頁 | `?page=1&per_page=20` |
| Records 回應格式 | JSON，含 `total`、`page`、`per_page`、`records[]` |
| Agg 回應格式 | JSON，含 `total_records`、`total_groups`、`groups[].key`、`groups[].stats.count` |