# 歐噴資料庫（data.openfun.tw）

台灣公共資料 API 平台，提供稅籍登記、選舉、採購、立法院議事等公共資料的結構化查詢。

---

## 第一步：搜尋有哪些資料

```
GET https://data.openfun.tw/api/v1/search?q=關鍵字
Authorization: Bearer YOUR_TOKEN   # 選填；帶 token 可額外搜到授權的 private dataset
```

一次回傳兩類結果：

- **`datasets.results`**：哪些資料集與關鍵字相關（含 `skill_md_url`，可直接讀查詢指南）
- **`entities.groups`**：搜尋到的真實人物 / 公司 / 機關出現在哪些資料集

不帶 token 只能搜到 public dataset；帶有效 Bearer Token 時，同時回傳使用者有群組授權的 private dataset。

**搜尋技巧：**
- 用白話或正式名稱：`?q=候選人得票`、`?q=開放文化基金會`、`?q=內政部`
- 兩類結果都值得看：entities 有結果但 datasets 沒有（或反之）很常見
- 最多試 2 次關鍵字，仍無結果則告知使用者找不到

**選用參數：**
- `per_dataset=N`（預設 5）：每個資料集最多顯示幾筆 entity
- `max_datasets=N`（預設 30）：entity 搜尋最多橫跨幾個資料集

---

## 第二步：讀取 AI 使用指引（**免 Token**）

找到 slug 後，先讀 skill.md——包含欄位說明、查詢範例、注意事項：

```bash
# 必須用 curl，不能用 WebFetch（WebFetch 會截斷內容）
curl -s "https://data.openfun.tw/datasets/{slug}/skill.md"
```

`skill_md_url` 欄位不空代表此資料集有 skill.md。

若需要更完整的背景說明，可另讀 knowledge.md（結構化知識文件，格式相同）：

```bash
curl -s "https://data.openfun.tw/datasets/{slug}/knowledge.md"
```

---

## 第三步：查詢資料（需 Token）

大部分資料集需要 Bearer Token。取得方式：

- **網頁申請**（長效 token，永不過期）：https://data.openfun.tw/user
- **Device Authorization Grant**（Claude Code / CLI 推薦，短效 24 小時）：

```bash
# 1. 發起授權，取得 user_code
curl -s -X POST https://data.openfun.tw/api/v1/auth/device \
  -H "Content-Type: application/json" \
  -d '{"device_name": "My Claude Session", "client": "claude-code"}'
# 回傳 user_code（格式 XXXX-XXXX）和 verification_uri_complete

# 2. 請使用者在瀏覽器開啟 verification_uri_complete，登入並點「同意授權」

# 3. 每 5 秒 poll 一次，直到取得 token
curl -s -X POST https://data.openfun.tw/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "device_code", "device_code": "opf_dev_..."}'
# pending 時：{"error": "authorization_pending"}
# 授權後：{"access_token": "ofk_...", "expires_in": 86400}
```

**如果使用者沒有 Token，優先引導使用 Device Authorization Grant 流程（使用者只需開瀏覽器按一下，不需手動複製貼上 token）。**

### 查詢記錄

```
GET https://data.openfun.tw/api/v1/datasets/{slug}/records
Authorization: Bearer YOUR_TOKEN
```

支援參數：`q`（全文搜尋）、`q[欄位名]`（欄位搜尋）、`{欄位名}=值`（精確篩選）、`{欄位名}>=值` / `{欄位名}<=值` / `{欄位名}>值` / `{欄位名}<值`（範圍篩選，適用日期與數字欄位）、`page`、`per_page`、`sort`、`fields`

回應：`{ total, page, per_page, records[], schema[] }`

### 統計聚合

```
GET https://data.openfun.tw/api/v1/datasets/{slug}/agg
Authorization: Bearer YOUR_TOKEN
```

支援參數：`group_by`（必填，keyword 欄位）、`field`（選填，數值欄位）、`{欄位名}=值`（精確篩選）、`{欄位名}>=值` 等範圍篩選（同 records 端點）

回應：`{ total_records, total_groups, groups[].key, groups[].stats.count }`，`field` 有傳時 stats 額外含 `sum/avg/min/max`

完整文件：https://data.openfun.tw/api-docs.md

---

## 資料邊界原則

每筆事實必須來自實際 API 查詢結果。

**歐噴查得到** → 以查詢結果回答，標明原始資料來源（每份 skill.md 的「資料來源」section 有原始機關名稱與網址）。

**歐噴查無** → 禁止生成「貌似資料庫紀錄」的回答。明示「歐噴資料庫未收錄此資料」，若有其他公開來源請建議使用者自行查詢。

---

## 常用資料集

以下為最常被詢問的資料集，search API 找不到時可直接使用。

| 需求 | Slug | Token |
|------|------|-------|
| 全國公司行號稅籍登記（統一編號） | `tw.gov.fia.eip~ref~business-tax` | 需要 |
| 歷屆候選人資料 | `tw.gov.cec~ref~candidates` | 需要 |
| 各行政區候選人得票數 | `tw.gov.cec~txn~candidates-votes` | 需要 |
| 現行法律條文全文 | `tw.gov.moj~ref~law` | 需要 |
| 政府機關代碼 | `tw.gov.dgpa~ref~gov-org` | 需要 |
| 行政區代碼 / 地圖 | `tw.openfun~entity~geo` | 需要 |
| 立法院議事（即時） | `tw.openfun~api~legislation` | 需要（但 skill.md 附有外部 API 網址，不需 Token 即可查） |
| 政府採購標案（每日） | `tw.openfun~api~procurement` | 需要（但 skill.md 附有外部 API 網址，不需 Token 即可查） |
| 政治獻金申報明細 | `tw.openfun~bulk~campaign-finance` | 需要（但 skill.md 附有靜態下載 URL，不需 Token 即可取） |
| SEGIS 統計（先查此找 slug） | `tw.gov.moi.segis~ref~product` | 需要 |

---

## Slug 命名慣例

格式：`{倒置網域}~{類型}~{識別碼}`

類型：`ref`（參考清單）、`txn`（交易/異動）、`stat`（統計）、`entity`（可查個別記錄）、`bulk`（大包下載）

**不要猜 slug**，一律從 search 結果或 skill.md 的關聯資料集取得。