Uedu Public API v1

快速開始

1. 前往「我的 API Keys」 建立一把金鑰
2. 將金鑰加入 HTTP header：Authorization: Bearer <your_api_key>
3. 呼叫 API endpoint，例如：

curl -H "Authorization: Bearer uedu_xxxxxxxx" \
  https://uedu.tw/api/v1/universities

認證

所有 /api/v1/* endpoint（除根路徑外）皆需要 API key。請使用 HTTP header：

Authorization: Bearer <your_api_key>

金鑰建立後只會完整顯示一次，請立即複製保存。資料庫僅儲存 SHA-256 hash，遺失需重建。

速率限制

• 每把金鑰每分鐘最多 60 次請求
• 每把金鑰每天最多 10,000 次請求
• 超過上限時回應 HTTP 429 Too Many Requests

如需更高額度，請聯絡平台管理員。

Endpoints

GET /api/v1/universities

取得大學列表。

Query 參數：

• region — （可選）篩選地區

GET /api/v1/courses

取得公開課程列表（僅 is_public=1 的課程）。

Query 參數：

• university — （可選）學校 code 或中文名稱
• semester — （可選）學期，例如 114-2
• q — （可選）課名關鍵字
• page — 預設 1
• page_size — 預設 20，最大 100

GET /api/v1/courses/<course_id>

取得單一公開課程詳情，包含課程目標與教學內容。

GET /api/v1/course_stats

歷年公開課程開設統計，可依學期、年份或學校分組（不含個人資料）。

Query 參數：

• university — （可選）學校 code 或中文名稱
• group_by — semester | year | school（預設 semester）

GET /api/v1/papers

Uedu 團隊已發表的學術論文列表（教學實踐研究成果）。

Query 參數：

• category — （可選）論文類別
• year — （可選）年份

GET /api/v1/conferences

Uedu 團隊參與的國際學術研討會列表。

可開放資料清單

以下是目前 Public API v1 與 MCP 對外提供的所有資料欄位。所有欄位皆屬於「公開課表級」低敏感資訊，敏感資料一律不會透過此 API 暴露。

1. 大學列表 /universities

• id、code、name_zh、name_en、short_name、region

2. 公開課程列表 /courses

僅包含教師明確設為「公開」的課程（is_public=1）

• 課程基本資料：id、class_name、course_number、course_class
• 中英文課名：course_name_chinese、course_name_english
• 授課教師：instructor、instructor_english
• 開課單位：department、department_english、school
• 時間：semester、start_date、end_date

3. 公開課程詳情 /courses/<id>

包含上述全部欄位，外加：

• 教學目標：teaching_goal、teaching_goal_english
• 教學內容大綱：teaching_content、teaching_content_english
• 課程備註：class_memo

4. 開課統計 /course_stats

• key（學期/年份/學校）、course_count、instructor_count
• 純彙總數據，不含任何個人資料

5. 學術論文 /papers

• slug、title、title_zh、authors、conference、year、doi、category、uedu_feature、award

6. 學術研討會 /conferences

• slug、name、name_short、year、dates、location、website、organizer、indexing、paper_count

回應格式

所有回應為 JSON，標準結構：

// 成功
{ "success": true, "data": {...} }
{ "success": true, "items": [...], "page": 1, "page_size": 20, "total": 150 }

// 失敗
{ "success": false, "error": "..." }

程式範例

Python (requests)

# pip install requests
import requests

API_KEY = "uedu_xxxxxxxx"
BASE = "https://uedu.tw/api/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

# 1. 列出大學
r = requests.get(f"{BASE}/universities", headers=headers)
print(r.json())

# 2. 搜尋課程
r = requests.get(f"{BASE}/courses", headers=headers, params={
    "university": "ncu",
    "semester": "114-2",
    "q": "人工智慧",
    "page": 1,
    "page_size": 20,
})
data = r.json()
for course in data["items"]:
    print(course["id"], course["class_name"], course["instructor"])

# 3. 取得課程詳情
r = requests.get(f"{BASE}/courses/123", headers=headers)
print(r.json()["data"])

# 錯誤處理
if r.status_code == 401:
    print("API key 無效或已撤銷")
elif r.status_code == 429:
    print("已超過速率限制，請稍後再試")
elif r.status_code == 404:
    print("找不到資源")

JavaScript (fetch)

const API_KEY = "uedu_xxxxxxxx";
const BASE = "https://uedu.tw/api/v1";
const headers = { "Authorization": `Bearer ${API_KEY}` };

// 搜尋課程
const params = new URLSearchParams({
  university: "ncu",
  semester: "114-2",
  page: 1,
  page_size: 20,
});

const res = await fetch(`${BASE}/courses?${params}`, { headers });
if (!res.ok) {
  if (res.status === 401) throw new Error("API key 無效");
  if (res.status === 429) throw new Error("速率限制");
  throw new Error(`HTTP ${res.status}`);
}
const data = await res.json();
console.log(data.items);

MCP Server（給 Claude 等 LLM 使用者）

我們提供了一個 MCP（Model Context Protocol）server，讓你可以直接在 Claude Desktop、Claude Code、Cursor、VS Code 等支援 MCP 的工具中，用自然語言查詢 Uedu 的公開資料，完全不需要寫程式。

安裝 MCP server

下載 uedu_mcp_server.py 並安裝依賴：

pip install "mcp[cli]" httpx
# 下載 server 腳本
curl -O https://uedu.tw/static/mcp/uedu_mcp_server.py

在你慣用的工具中設定

Claude Desktop

編輯設定檔：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "uedu": {
      "command": "python",
      "args": ["/absolute/path/to/uedu_mcp_server.py"],
      "env": {
        "UEDU_API_KEY": "uedu_xxxxxxxx"
      }
    }
  }
}

儲存後重啟 Claude Desktop 即可生效。

Claude Code (CLI)

使用內建指令快速新增：

claude mcp add uedu \
  --env UEDU_API_KEY=uedu_xxxxxxxx \
  -- python /absolute/path/to/uedu_mcp_server.py

Cursor

編輯 ~/.cursor/mcp.json （全域）或專案內 .cursor/mcp.json：

{
  "mcpServers": {
    "uedu": {
      "command": "python",
      "args": ["/absolute/path/to/uedu_mcp_server.py"],
      "env": {
        "UEDU_API_KEY": "uedu_xxxxxxxx"
      }
    }
  }
}

在 Cursor 的「Settings → MCP」頁面也可以圖形化新增。

VS Code（原生 MCP 支援）

VS Code 已內建 MCP 支援（不限於 Copilot Chat）。三種新增方式：

• 命令面板執行 MCP: Add Server，依引導流程完成
• 使用者層級：執行 MCP: Open User Configuration 編輯使用者 mcp.json
• 工作區層級：在專案根目錄手動建立 .vscode/mcp.json

{
  "servers": {
    "uedu": {
      "type": "stdio",
      "command": "python",
      "args": ["${workspaceFolder}/uedu_mcp_server.py"],
      "env": {
        "UEDU_API_KEY": "uedu_xxxxxxxx"
      }
    }
  }
}

macOS / Linux 使用者建議啟用 sandbox，限制 server 只能存取 Uedu 網域：

{
  "servers": {
    "uedu": {
      "type": "stdio",
      "command": "python",
      "args": ["${workspaceFolder}/uedu_mcp_server.py"],
      "env": { "UEDU_API_KEY": "uedu_xxxxxxxx" },
      "sandboxEnabled": true,
      "sandbox": {
        "filesystem": { "allowWrite": [] },
        "network": { "allowedDomains": ["uedu.tw"] }
      }
    }
  }
}

首次啟動時 VS Code 會跳出「信任此 server」對話框，確認後即可使用。Continue 擴充套件也可填入相同的 server 區塊。

HTTP 模式（experimental，免安裝 Python）

我們同時提供 streamable-http transport 的 MCP server，client 端只需在設定檔填入 URL 與 API key，無需在本機安裝 Python 或任何依賴。適合非工程背景的使用者。

VS Code .vscode/mcp.json：

{
  "servers": {
    "uedu": {
      "type": "http",
      "url": "https://uedu.tw/mcp",
      "headers": {
        "Authorization": "Bearer uedu_xxxxxxxx"
      }
    }
  }
}

Cursor / Claude Desktop（支援 http transport 的版本）：

{
  "mcpServers": {
    "uedu": {
      "url": "https://uedu.tw/mcp",
      "headers": {
        "Authorization": "Bearer uedu_xxxxxxxx"
      }
    }
  }
}

使用範例（自然語言對話）

設定完成後，直接在對話中問：

• 「Uedu 上中央大學 114-2 學期有哪些公開課程？」
• 「幫我找一門課名包含『人工智慧』的課，並列出授課教師」
• 「課程 id 1234 的詳情是什麼？」
• 「Uedu 收錄了哪些北部的大學？」

LLM 會自動呼叫對應的 MCP tool，回傳結果並用自然語言摘要。

使用條款

• 本 API 僅提供低敏感的公開課程與學校資料，不包含學生名單、成績、論壇貼文、AI 對話紀錄或生理數據
• 不可用於商業大量爬取或轉售資料
• 使用本 API 取得的資料時，請註明來源「Uedu 優學院 (uedu.tw)」
• 濫用或違反條款可能導致金鑰被撤銷