---
group: 開發者文件
order: 10
---
# 歐噴資料庫 API 文件

歐噴資料庫提供 REST API，讓你查詢所有資料集。

基底 URL：`https://data.openfun.tw/api/v1`

## 認證

所有 API 端點皆需 API Token。請前往 https://data.openfun.tw/user 免費申請帳號與 Token。

每次請求在 HTTP Header 帶上：

```
Authorization: Bearer {your-token}
```

---

## 端點總覽

| 端點 | 用途 |
|------|------|
| `GET /api/v1/datasets` | 列出所有資料集 |
| `GET /api/v1/datasets/{slug}` | 查詢單一資料集 metadata |
| `GET /api/v1/datasets/{slug}/records` | 查詢記錄（搜尋、篩選、分頁） |
| `GET /api/v1/datasets/{slug}/records/{id}` | 查詢單一記錄 |
| `GET /api/v1/datasets/{slug}/agg` | 統計聚合（按欄位分組計數） |

---

## 查詢記錄（records 端點）

```
GET /api/v1/datasets/{slug}/records
```

### 查詢參數

| 參數 | 說明 | 範例 |
|------|------|------|
| `q` | 全文搜尋（對所有 text 欄位） | `q=台積電` |
| `q[欄位名]` | 欄位指定全文搜尋 | `q[營業地址]=台北市` |
| `{欄位名}` | keyword 欄位精確比對 | `組織別名稱=有限公司` |
| `_ids` | 批次查詢多個 ID（逗號分隔） | `_ids=A001,A002,A003` |
| `page` | 頁碼，從 1 開始 | `page=2` |
| `per_page` | 每頁筆數，預設 20，最大 100 | `per_page=50` |
| `sort` | 排序，欄位名後接 `<`（降冪）或 `>`（升冪） | `sort=資本額<` |
| `fields` | 只回傳指定欄位（逗號分隔） | `fields=統一編號,營業人名稱` |

> **注意**：只有 `keyword` 或 `number` 型別欄位支援精確比對（`{欄位名}=值`）。`text` 型別請用 `q=` 或 `q[欄位名]=`。

### 回應格式

```json
{
  "total": 1750000,
  "page": 1,
  "per_page": 20,
  "records": [
    { "統一編號": "04541302", "營業人名稱": "台灣積體電路製造股份有限公司", ... }
  ],
  "schema": [...]
}
```

| 欄位 | 說明 |
|------|------|
| `total` | 符合條件的總筆數 |
| `page` | 目前頁碼 |
| `per_page` | 每頁筆數 |
| `records` | 本頁記錄陣列 |
| `schema` | 欄位定義（含欄位名稱、型別、篩選條件等） |

---

## 統計聚合（agg 端點）

```
GET /api/v1/datasets/{slug}/agg
```

用途：按某 keyword 欄位分組，統計各組的筆數（及數值欄位的統計量）。適合「各縣市有幾家」、「各類型分布」等問題——一次查詢取得所有分組，不需逐一查詢。

### 查詢參數

| 參數 | 必填 | 說明 |
|------|------|------|
| `group_by` | 是 | 分組欄位名稱（必須是 keyword 型別） |
| `field` | 否 | 數值欄位名稱（若提供，會計算 sum/avg/min/max） |
| `{欄位名}` | 否 | 與 records 端點相同的篩選條件 |

### 只計數

省略 `field`，只取得各組的筆數：

```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,
  "total_groups": 22,
  "groups": [
    { "key": "66000", "stats": { "count": 1663 } },
    { "key": "65000", "stats": { "count": 1537 } }
  ]
}
```

### 同時計算數值統計

加上 `field` 參數，`stats` 會增加 sum、avg、min、max、percentiles：

```bash
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/agg?group_by=營業地址.縣市&field=資本額&行業代號=932414"
```

回應的 `stats` 格式：

```json
{
  "count": 1663,
  "sum": 258971407,
  "avg": 155725.44,
  "min": 0,
  "max": 21000000,
  "percentiles": { "25": 30000, "50": 70000, "75": 100000 }
}
```

---

## 範例

### 搜尋公司

```bash
# 全文搜尋
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?q=積體電路"

# 精確比對 + 排序
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/records?組織別名稱=股份有限公司&sort=資本額<&per_page=10"
```

### 分組統計

```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"

# 進一步到鄉鎮層級
curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://data.openfun.tw/api/v1/datasets/tw.gov.fia.eip~ref~business-tax/agg?group_by=營業地址.鄉鎮市區&行業代號=932414"
```

---

## 資料集目錄

查看所有可查詢的資料集：[catalog.md](https://data.openfun.tw/catalog.md)

每個資料集的詳細查詢說明（欄位、範例、注意事項）在各自的 skill.md：
`https://data.openfun.tw/datasets/{slug}/skill.md`