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[欄位名]=。

回應格式

{
  "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，只取得各組的筆數：

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

回應：

{
  "total_records": 10969,
  "total_groups": 22,
  "groups": [
    { "key": "66000", "stats": { "count": 1663 } },
    { "key": "65000", "stats": { "count": 1537 } }
  ]
}

同時計算數值統計

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

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 格式：

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

範例

搜尋公司

# 全文搜尋
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"

分組統計

# 某行業各縣市分布
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

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

📄 查看原始 Markdown