ntut-course-crawler

國立臺北科技大學課程資料的非官方靜態 API。

每 4 小時自動爬取學校課程查詢系統，轉成結構化 JSON 後發布到 GitHub Pages。 沒有伺服器、沒有資料庫、不需要 API key —— 直接 fetch() 就能用。

資料依系所 / 教師 / 班級 / 學程 / 教室 / 時段分別建索引， 查一位老師的課不必先下載全校兩千多門課。

涵蓋 90-1 至 115-1 共 51 個學期、141,018 門課（民國 90 年起，約 25 年）。 課程數是 2026-09-05 的實測值，選課期間會小幅變動；即時數字請讀 meta.json 的 semesters[].course_count。

---

API base URL

https://tntrock.github.io/ntut-course-crawler/

下面所有路徑都是相對於這個 base URL。{semester} 例如 115-1。

所有回應都帶 Access-Control-Allow-Origin: *，瀏覽器可以直接跨網域 fetch()， 不需要 proxy。Content-Type 是 application/json; charset=utf-8， Cache-Control 是 max-age=600（GitHub Pages 的設定，本專案改不了）。

我想查…

我想查	打這支	例
現在有哪幾個學期、有什麼端點	meta.json
關鍵字搜尋全部課程	{semester}/index.json	115-1/index.json
某個系所的課	{semester}/courses/{系所代碼}.json	115-1/courses/59.json
某個老師的課	{semester}/teachers/{教師代碼}.json	115-1/teachers/12095.json
某個班級的課表	{semester}/classes/{班級代碼}.json	115-1/classes/2915.json
有哪些老師 / 班級 / 系所	{semester}/teachers.json、classes.json、departments.json
某個學程有哪些課	{semester}/programs.json
某間教室排了什麼課	{semester}/classrooms.json
星期幾第幾節有什麼課（找空堂、擋修衝堂）	{semester}/schedule.json
最近有哪些課 / 老師被加開、停開、調課、換人	changes.json
退選率、修課人數	課程物件的 enrolled / withdrawn（見下）
退選率隨時間的走勢	enrollment.json
某門課的教學大綱（進度、評量、教材、SDGs）	{semester}/syllabus/{課號}.json	115-1/syllabus/364893.json

不知道代碼？先拉 {semester}/departments.json、teachers.json、classes.json， 每一筆都附了 path 欄位，直接接在 base URL 後面就是明細檔的網址。

端點總覽

路徑	內容	115-1 實際大小
meta.json	學年期清單、端點清單、節次與必選修對照	13 KB
index.json	最新兩個學期的課程輕量索引	1.5 MB（gzip 149 KB）
errors.json	目前的抓取失敗與警告（學期、單位、班級、大綱、教室容量）	通常 < 10 KB
runs.json	最近 120 次抓取的執行紀錄，含失敗與逾時（見下）	約 50 KB
changes.json	最近的課程與教師異動事件（見下）	隨異動量變動
enrollment.json	修課 / 撤選人數逐日快照的索引（見下）	隨天數變動
{semester}/enrollment/{date}.json	某一天的逐課修課 / 撤選人數	約 120 KB / 天
capacity.json	教室容量（座位數）	約 52 KB
syllabus.json	教學大綱的抓取進度與逐課狀態（見下）	隨課數變動
{semester}/syllabus/{course_id}.json	單一課程的教學大綱與進度	約 3–8 KB / 門
{semester}/index.json	單一學期的課程輕量索引	711 KB
{semester}/departments.json	學院 / 系所 / 班級三層對照	48 KB
{semester}/courses/{department_id}.json	系所課表（完整課程物件）	60 檔，共 1.5 MB
{semester}/teachers.json	教師清單	89 KB
{semester}/teachers/{teacher_id}.json	教師課表（完整課程物件）	803 檔，共 1.7 MB
{semester}/classes.json	班級清單	70 KB
{semester}/classes/{class_id}.json	班級課表（完整課程物件）	286 檔，共 1.7 MB
{semester}/programs.json	學程 → 課號	16 KB
{semester}/classrooms.json	教室 → 課號	51 KB
{semester}/schedule.json	星期 × 節次 → 課號	55 KB

根目錄 / 是一頁靜態說明頁。要拿最新兩個學期的索引請明確打 /index.json。

同一組資料另外有三頁給人看的：/status.html（爬蟲跑得如何、各學期資料多新、 大綱補到哪、人數快照）、/errors.html（目前抓不到的單位與課程）、 /changes.html（最近的加開、停開、調課與教師異動）。 它們只讀上表這些 JSON，沒有後端 —— 你自己也可以照樣讀。

明細檔（courses/ teachers/ classes/）放完整課程物件，拿到就能直接顯示， 不必再載別的檔對照。清單檔（teachers.json classes.json …）只放 「有哪些、各幾門課」，做下拉選單時不會被整包資料拖慢。

programs.json / classrooms.json / schedule.json 只放課號 —— 拿課號去 {semester}/index.json 或系所明細檔查即可，避免同一份課程資料被複製太多份。

changes.json：最近的異動

排程每 4 小時重跑一次，但大部分時候資料一個字都沒變。光看檔案時間戳 分不出「只是重跑」和「學校真的動了課」，要確認就得自己下載前後兩版來 diff。

changes.json 是一條事件流：一筆異動一個事件、各自帶偵測到的時間， 最新的在最前面。想知道最近發生什麼，讀開頭幾筆就好。

{
  "checked_at": "2026-09-04T12:03:11Z",
  "event_count": 4,
  "events": [
    {
      "at": "2026-09-04T12:03:11Z", "semester": "115-1",
      "type": "course_removed",
      "id": "361339", "name": "體育",
      "teachers": [], "department_ids": ["59"], "class_ids": ["2915"]
    },
    {
      "at": "2026-09-04T12:03:11Z", "semester": "115-1",
      "type": "course_changed",
      "id": "364893", "name": "數位影像處理",
      "teachers": ["陳香君"], "department_ids": ["59"], "class_ids": ["2915"],
      "changes": { "teachers": { "from": ["白敦文"], "to": ["陳香君"] } }
    },
    {
      "at": "2026-09-04T08:03:07Z", "semester": "115-1",
      "type": "teacher_removed",
      "id": "12095", "name": "白敦文",
      "course_count": 1, "department_ids": ["59"]
    }
  ]
}

type	意思	特有欄位
course_added	加開一門課
course_removed	停開一門課
course_changed	課的內容變了	changes（逐欄位的 from / to）
teacher_added	這學期多了一位老師	course_count（他開幾門課）
teacher_removed	這學期少了一位老師	course_count（消失前開幾門課）
baseline	第一次抓到這個學期，沒有基準可比	course_count
bulk_change	一次異動量太大，折成摘要	counts、by_department、by_class、samples

• at 是偵測到的時間，不是學校異動的時間 —— 實際異動發生在上一次抓取 與這次之間，最多相差 4 小時。

• course_removed 是跟學校查證過的。 課從資料集消失有兩種可能：真的停開， 或者我們那一輪讀錯了。只有「消失」還不夠 —— 每一筆都會再去問學校的教學大綱頁， 它回「查無課號」才記成停開。問不出結論的那一輪整個不發布，寧可晚 4 小時， 也不要在這裡放一筆假的停開。

• 加欄位不算異動。 比對只看兩邊都有的欄位 —— 索引的欄位會隨程式演進而 增加，新欄位第一次出現時舊索引裡根本沒有那個 key，把它當成「從 null 變成 某值」會讓全校幾百門課一次全部變成 course_changed。那不是學校動了資料。

• 事件是 append-only 的，寫下去就不會再改。 所以舊事件可能缺少後來才加的 欄位（例如 2026-09-04 10:24 之前寫入的 bulk_change 沒有 by_department / by_class / samples）。使用端請把 type 以外的欄位一律當成選填， 缺了就降級顯示，不要假設一定存在。

• checked_at 是最後一次比對的時間，沒有異動時也會更新。所以 「checked_at 是今天但沒有新事件」＝學校真的沒動； 「checked_at 停在三天前」＝爬蟲沒在跑。

• course_changed 比對的欄位是課名、教師、時段、學分、必選修、開課系所、班級。

• 教師事件是用教師代碼比對的，不是姓名 —— 115-1 實測 803 個代碼只對到 801 個姓名，確實有同名老師。換人授課時課還在，只有教師端看得出少了誰。

• 最多保留 500 筆事件。

• 只有最新兩個學期會產生事件 —— 比對基準是頂層 index.json，它只涵蓋 那兩個。第一次抓到某個學期時記成 baseline，不會變成「新增兩千多門課」。

• 單次超過 200 筆異動會折成一筆 bulk_change，避免把先前真正的異動整個 推出保留範圍。摘要會帶依系所與班級的分組統計加上前 10 筆完整樣本， 所以不必再自己去 diff。2026-09-04 實際遇到的那次長這樣：

  {
    "type": "bulk_change", "event_count": 267,
    "counts": { "course_added": 265, "course_removed": 2 },
    "by_department": { "01": 185, "14": 80, "36": 1, "37": 1 },
    "by_class": { "589": 80, "2519": 42, "2520": 38, "2522": 35,
                  "2524": 32, "2523": 28, "2521": 10, "…": 1 },
    "samples": [ { "type": "course_added", "id": "367177",
                   "name": "全球化與多元文化", "class_ids": ["589"] } ]
  }
  

  兩個單位、7 個班級 —— 一眼就看得出是學校開了一批跨校選課（589 博雅選修 跨校、2519–2524 與北大 / 北醫 / 海大的跨校選課），而不是解析器壞了。 真的抓歪時分組會散落在幾十個系所，一樣一眼分得出來。 by_department 全列（系所頂多 60 個），by_class 只留量最大的 20 個。 一門課可能同時掛多個系所或班級，所以分組數量的總和會大於 event_count。

修課人數與退選率

學校的課程表本身就有「人」和「撤」兩欄，所以不必去抓教學大綱：

欄位	意思
enrolled	修課人數（原始頁面的「人」欄）
withdrawn	撤選人數（原始頁面的「撤」欄）
quota	enrolled 的舊名，已棄用，值完全相同

quota 這個名字會讓人以為是名額上限，其實一直都是修課人數 —— 114-2 全校有 111 種不同的值、只有 21% 是 5 的倍數，名額上限不會長這樣。 舊欄位保留不刪（見相容性承諾），新的程式請用 enrolled。

兩個欄位在課程物件（{semester}/courses/、teachers/、classes/ 的明細檔） 和輕量索引（index.json、{semester}/index.json）裡都有，所以算全校退選率 不必先下載 60 個系所明細檔。

分母要用哪一個

人 到底是撤選後的現存人數，還是含撤選的原始人數，學校沒有說明， 從資料本身也判斷不出來。兩種算法在全校層級差很小，但對單一課程差很多：

撤 / 人          ← 若「人」不含撤選的人
撤 / (人 + 撤)   ← 若「人」是撤選後的現存人數

114-2 全校實測：修課 73,403 人次、撤選 1,596 人次 → 兩種算法分別是 2.17% 與 2.13%。但那門撤選 17 人、現存 30 人的 「物件導向程式設計」，兩種算法是 56.7% 和 36.2%，差很多。

要判定的話：115-1 的撤選期還沒到（「撤」目前全是 0）， 等撤選開始後看某門課的 enrolled 會不會隨 withdrawn 上升而下降就知道了。 enrollment.json 的逐日快照正是為了留下這段資料。

enrollment.json：人數的時間軸

明細檔裡的人數是當下的值，每次抓取直接覆蓋。學期結束後那是定案的數字， 拿來算退選率沒問題；但「哪門課在第幾週被大量退掉」這種問題，快照沒留下來 就永遠答不了，而且錯過了要再等一個學期。

所以每天存一份（依台灣時區切日，同一天內重複抓取就覆蓋當天那份）：

{
  "snapshot_count": 12,
  "snapshots": [
    { "semester": "115-1", "date": "2026-09-05",
      "at": "2026-09-05T12:03:11Z",
      "course_count": 2717,
      "enrolled_total": 73403, "withdrawn_total": 1596,
      "path": "115-1/enrollment/2026-09-05.json" }
  ]
}

• 根目錄的 enrollment.json 只放每天的總計，全校退選率的走勢靠它就畫得出來。
• 要看是哪幾門課，再去拿當天的 {semester}/enrollment/{date}.json， 裡面是逐課的 id / enrolled / withdrawn。
• 逐日快照只新增、不改寫，最多保留 400 筆索引。

人數的變動刻意不進 changes.json。 加退選期間每 4 小時就有上千門課的 人數在動，塞進事件流會每次都觸發 bulk_change，把真正的結構性異動 （加開、停開、調課、換老師）整個淹掉 —— 兩種資料的變動頻率差一個數量級。

執行紀錄 runs.json

「爬蟲現在怎麼樣了」這件事，GitHub Actions 的 log 回答不了——它要登入點進去 或帶 token 打 API，而且只留 90 天。一個靜態的狀態頁需要的是一份跟資料放在 一起、直接 fetch() 就拿得到的紀錄。這個檔就是。

{
  "schema_version": 3,
  "generated_at": "2026-09-05T12:31:07Z",
  "run_count": 47,
  "runs": [
    {
      "at": "2026-09-05T12:31:07Z",
      "workflow": "backfill",
      "status": "success",
      "event": "workflow_dispatch",
      "run_id": "33959063005",
      "attempt": 1,
      "url": "https://github.com/tntrock/ntut-course-crawler/actions/runs/33959063005",
      "attempts": 1,
      "detail": true,
      "attempt_started_at": "2026-09-05T09:51:02Z",
      "requests_ok": 7100,
      "failed_urls": 0,
      "cache_hits": 0,
      "exit_code": 0,
      "semesters": [
        {"semester": "114-2", "courses": 2809, "departments_ok": 61,
         "departments_failed": 0, "errors": 0, "seconds": 524.8,
         "syllabus_fetched": 1968, "syllabus_written": 1968}
      ],
      "failed_semesters": []
    }
  ]
}

• 最新的在最前面，保留最近 120 筆（一天八班約兩週）
• status 是 job 的狀態，不是爬蟲的回傳值：success / failure / cancelled （job 逾時被砍算 cancelled）
• detail: false 代表爬蟲沒能寫出側寫檔——被砍在半路，或更早的步驟就失敗了。 這時 semesters 等欄位整組不存在。刻意不填 0，那會被讀成 「跑了但什麼都沒抓到」，跟「根本沒跑到」是兩回事
• 同一個 run_id + attempt 只會有一筆；重試是新的 attempt，各自一筆
• 兩種「重試」不要搞混：attempt 是 GitHub 的 re-run 按鈕， attempts 是 workflow 內部那個「等 30 分鐘整批重來」的迴圈跑了幾次。 「一次就過」跟「重試三次才過」對狀態頁是兩回事
• requests_ok 只算成功的請求，要跟 failed_urls（重試到底仍然放棄的網址數） 一起看。2026-09-05 那次回補失敗就是 requests_ok: 0 配 failed_urls: 3 —— 連學校的門都沒摸到
• attempt_started_at 是最後那一次嘗試的開始時間。整批重試每次都重跑一個 新的行程、重寫側寫檔，所以它不等於整個 run 的開始時間（那個看 url 進去查）

要做狀態頁的話，這幾個檔合起來就夠了：runs.json（最近跑得如何）、 meta.json 的 semesters[].generated_at（每個學期的資料多新）、 errors.json（現在有哪些東西抓不到）、syllabus.json（大綱補到哪了）。 全部都是 CORS 開放的靜態 JSON，前端直接 fetch()。

教學大綱

課程物件的 syllabus_url 是學校原始頁面的網址； {semester}/syllabus/{課號}.json 是解析過的內容：

{
  "course_id": "364893", "course_name": "數位影像處理",
  "teachers": ["白敦文"], "department_ids": ["59"],
  "url": "https://aps.ntut.edu.tw/course/tw/ShowSyllabus.jsp?snum=364893&code=12095",
  "updated_at": "2026-08-11T01:00:23Z",
  "has_content": true,
  "content_hash": "3f8a1c04b27de591",

  "teacher_name": "白敦文", "teacher_email": "[email protected]",
  "outline": "This course will be lectured in Chinese/English…",
  "schedule": "1. Introduce to Image Processing\nAI applications\n…",
  "flexible_learning": {
    "category": ["學生分組實作及討論", "AI 輔助學習與工具應用", "遠距教學"],
    "content": "…", "hours": 3, "outcome": "…", "assessment_ratio": "…"
  },
  "assessment": "Quiz:15%, Homework:15%, Midterm 35%, Final 35%.",
  "materials": "…", "contact": ["研究室分機(Extension): 4222", "…"],
  "extended_resources": ["混成學習 (Blended Learning)", "…"],
  "sdgs": ["SDG4：優質教育（Quality Education）", "…"],
  "ai_usage": ["使用生成式AI作為教學過程的輔助工具", "…"],
  "notes": "…"
}

• updated_at 是老師最後修改大綱的時間（學校顯示台灣時間，這裡轉成 UTC， 跟全站其他時間戳一致）。
• content_hash 是這份內容的指紋（sha256 前 16 個 hex 字）。內容沒變就不會重寫這個檔， 所以拿它當快取鍵是安全的。我們抓下來的時間不在這個檔裡，請查 syllabus.json。
• has_content 為 false 代表老師還沒填。檔案仍然會產生 —— 沒有它的話， 每次執行都會再去問一次同一頁。
• 條列式的欄位（sdgs、ai_usage、contact、extended_resources）輸出成陣列， 項目符號已去掉。長文欄位（outline、schedule、materials）保留原樣的換行， 不自作聰明切開。
• 認不得的欄位不會被丟掉，會原樣收進 extra。學校加新欄位時 （SDGs 和「是否導入 AI」顯然就是近年才加的）才不會靜靜漏抓半年。

更新頻率與涵蓋範圍

• 當期大綱一天全量更新兩班（台灣 09、21 時），最多落後半天。
• 大綱涵蓋 90-1 以後的全部學期。 但越早的學期掛大綱的課越少：96 學年度以後 約七成的課有大綱，95 學年度約一成，90～92 學年度只有 1% 左右。
• 大綱檔沒有抓取時間，內容沒變就不會重寫。要知道某門課上次什麼時候抓的， 查 syllabus.json 的 fetched[學期][課號].at。

syllabus.json 的三個區塊

{
  "schema_version": 3,
  "semesters": [
    {"semester": "115-1", "fetched": 1909, "with_url": 1909, "course_count": 2717,
     "oldest_fetch": "2026-09-05T06:01:09Z", "newest_fetch": "2026-09-05T06:41:05Z"},
    {"semester": "114-2", "fetched": 1968, "with_url": 1968,
     "frozen": true, "frozen_at": "2026-09-06T02:11:40Z"}
  ],
  "fetched": {
    "115-1": {"360744": {"at": "2026-09-05T06:01:09Z", "hash": "3f8a1c04b27de591"}}
  },
  "frozen": {"114-2": {"fetched": 1968, "with_url": 1968, "at": "2026-09-06T02:11:40Z"}}
}

• semesters 是給人看的進度，一個學期一列
• fetched 是給下一次執行看的逐課狀態（抓取時間 + 內容雜湊）
• frozen 是已經補完、逐課狀態收掉了的歷史學期，只留門數

semesters[].fetched 是進度的分子：現在還有大綱連結、而且已經抓過的 門數。它跟頂層 fetched 的筆數不一定相等——課換了老師，學校的大綱連結 會跟著消失，但抓過的那筆逐課狀態刻意留著（連結回來時不必重抓）。 分母 with_url 是當下有連結的門數，所以進度不會超過 100%。

為什麼檔名是代碼而不是中文？

中文檔名在 GitHub Pages 上會被 percent-encoding，使用者得自己處理 URL 編碼； 而且系所會改名，代碼相對穩定。中文名稱在各清單檔裡提供對照。

---

系所代碼對照

{semester}/courses/{代碼}.json 的代碼。代碼是字串不是數字 （"01" 有前導零，"C5" 有英文字母），JSON 解析時不要當整數處理。

以下為 115-1 實際抓到的 60 個單位；學校新增單位時 departments.json 會即時反映， 這張表只是方便閱讀的快照。

電資學院

代碼	系所	代碼	系所
31	電機系	36	電子系
59	資工系	65	光電系
82	電資學士班	99	電資外國學生專班
AY	太空所	C5	電資學院

機電學院

代碼	系所	代碼	系所
2B	智動科	30	機械系
40	機電所	44	車輛系
45	能源冷凍空調系	56	製科所
61	自動化所	66	機電科所
81	機電學士班	A8	機電科技博士外生專班
AG	機械自動化外生專班	B2	半導體學士學位學程
B3	半導體外生專班	C0	機電學院

工程學院

代碼	系所	代碼	系所
32	化工系	33	材資系
34	土木系	35	分子系
42	防災所	51	高分所
60	環境所	68	生化所
73	化工所	78	材料所
79	資源所	83	工程科技學士班
A0	能源光電外國學生專班

管理學院

代碼	系所	代碼	系所
37	工管系	57	經管系
74	管理所	98	管理外國學生專班
AB	資財系	C2	管理學院

設計學院

代碼	系所	代碼	系所
38	工設系	39	建築系
52	建都所	58	創新所
84	創意設計學士班	85	設計所
AC	互動系	AT	互動與創新外生專班

人文與社會科學學院

代碼	系所	代碼	系所
49	技職所	54	英文系
91	科技法律學程	A4	智財所
A5	文發系

創新前瞻科技研究學院

代碼	系所
C7	創新學院

行政 / 校級單位（college 為 null）

代碼	系所	代碼	系所
01	教務處	10	體育室
14	通識中心	62	師資培育中心
AA	校院級課程

C0 C2 C5 C7 這種「學院」單位掛的是院級共同課程， 不是把該學院所有系的課集合起來。要一個學院的全部課程， 請照 departments.json 的 colleges 分組，逐系所取。

---

範例

meta.json

{
  "schema_version": 3,
  "generated_at": "2026-09-04T02:03:11Z",
  "source": { "name": "國立臺北科技大學 課程查詢系統", "url": "https://aps.ntut.edu.tw/course/tw/" },
  "disclaimer": "本資料由非官方爬蟲自動蒐集,僅供參考…",
  "latest": "115-1",
  "semesters": [
    {
      "year": 115, "sem": 1, "path": "115-1",
      "generated_at": "2026-09-04T02:03:11Z",
      "partial": false,
      "department_count": 60,
      "class_group_count": 286,
      "course_count": 2455,
      "merged_course_count": 310,
      "failed_department_count": 0
    }
  ],
  "endpoints": [
    { "path": "{semester}/teachers/{teacher_id}.json", "description": "教師課表" }
  ],
  "periods": [{ "code": "1", "start": "08:10", "end": "09:00" }],
  "requirement_symbols": [{ "symbol": "★", "required": false, "requirement_type": "專業選修" }]
}

latest 是目前最新的學年期。不要把學年期寫死在前端，讀這個欄位。

115-1/teachers.json → 115-1/teachers/12095.json

{
  "teacher_count": 803,
  "teachers": [
    {
      "id": "12095",
      "name": "白敦文",
      "course_count": 3,
      "department_ids": ["59", "C5"],
      "path": "115-1/teachers/12095.json"
    }
  ]
}

{
  "schema_version": 3,
  "year": 115, "sem": 1,
  "teacher": {
    "id": "12095",
    "name": "白敦文",
    "department_ids": ["59", "C5"],
    "url": "https://aps.ntut.edu.tw/course/tw/Teach.jsp?format=-3&year=115&sem=1&code=12095"
  },
  "course_count": 3,
  "courses": [ { "id": "364893", "name_zh": "數位影像處理", "...": "完整課程物件" } ]
}

教師以代碼為準，不是姓名。 115-1 有 803 個教師代碼但只有 801 個不同姓名 —— 確實有同名老師，用姓名分組會把兩個人的課混在一起。 程式對「有姓名但沒有 Teach.jsp 連結」的老師會輸出 id 與 path 為 null， 但實際資料裡沒有這種情形（90-1 至 115-1 抽查皆為 0 筆）—— 沒有指定教師的課（115-1 有 504 門，多為班週會）根本不會產生教師條目。

115-1/classes.json → 115-1/classes/2915.json

{
  "class_count": 286,
  "classes": [
    {
      "id": "2915",
      "name": "資工四",
      "department_id": "59",
      "department_name": "資工系",
      "college": "電資學院",
      "course_count": 53,
      "url": "https://aps.ntut.edu.tw/course/tw/Subj.jsp?format=-4&year=115&sem=1&code=2915",
      "path": "115-1/classes/2915.json"
    }
  ]
}

明細檔結構與教師檔相同：class_group + course_count + courses。

班級代碼（2915）和系所代碼（59）是兩組不同的 ID，互相推不出來。

115-1/departments.json

{
  "schema_version": 3,
  "year": 115, "sem": 1,
  "departments": [
    {
      "id": "59",
      "name": "資工系",
      "college": "電資學院",
      "url": "https://aps.ntut.edu.tw/course/tw/Subj.jsp?format=-3&year=115&sem=1&code=59",
      "class_groups": [
        { "id": "2915", "name": "資工四", "url": "…format=-4…code=2915" }
      ],
      "course_count": 53,
      "path": "115-1/courses/59.json"
    }
  ],
  "colleges": [
    { "name": "電資學院", "department_ids": ["31", "36", "59", "65", "82", "99", "AY", "C5"] },
    { "name": null, "department_ids": ["01", "10", "14", "62", "AA"] }
  ]
}

115-1/courses/59.json

{
  "schema_version": 3,
  "year": 115, "sem": 1,
  "department": { "id": "59", "name": "資工系", "college": "電資學院", "url": "…" },
  "course_count": 53,
  "courses": [
    {
      "id": "364893",
      "name_zh": "數位影像處理",
      "name_en": null,
      "stage": "1",
      "credits": 3.0,
      "hours": 3,
      "required": false,
      "requirement_type": "專業選修",
      "teachers": ["白敦文"],
      "teacher_codes": ["12095"],
      "classes": ["資工四"],
      "class_ids": ["2915"],
      "department_ids": ["59"],
      "time_slots": [{ "day": 5, "day_name": "五", "periods": ["2", "3", "4"] }],
      "classrooms": ["六教727(e)"],
      "classroom_codes": ["452"],
      "enrolled": 22,
      "quota": 22,
      "withdrawn": 0,
      "language": null,
      "syllabus_url": "https://aps.ntut.edu.tw/course/tw/ShowSyllabus.jsp?snum=364893&code=12095",
      "notes": "資工四和資工所合開",
      "audit": null,
      "lab": null,
      "programs": ["人工智慧科技學程", "光電智慧製造學程"]
    }
  ]
}

115-1/index.json / index.json

只放搜尋與篩選需要的欄位，細節到明細檔取。 teacher_codes / class_ids / department_ids 讓你能從搜尋結果直接跳到對應的明細檔。

{
  "schema_version": 3,
  "covers": ["115-1", "114-2"],
  "course_count": 5264,
  "courses": [
    {
      "id": "364893",
      "name_zh": "數位影像處理",
      "teachers": ["白敦文"],
      "teacher_codes": ["12095"],
      "time_slots": [{ "day": 5, "day_name": "五", "periods": ["2", "3", "4"] }],
      "department_ids": ["59"],
      "class_ids": ["2915"],
      "credits": 3.0,
      "required": false,
      "requirement_type": "專業選修",
      "language": null,
      "enrolled": 22,
      "withdrawn": 0,
      "year": 115,
      "sem": 1
    }
  ]
}

索引裡的 language 讓「只看全英語授課」不必下載 60 個系所明細檔 （115-1 全校 2,717 門裡有 499 門非中文：英語 488、中英雙語 11）。 enrolled / withdrawn 同理，是為了讓算退選率只需要一個檔。

頂層 index.json 只含 covers 列出的那幾個學期（目前是最新兩個）。 更早的學期不在裡面，請改讀 {semester}/index.json —— 那些檔案抓過一次 就不會再變，很適合長期快取。

115-1/programs.json / classrooms.json

{
  "program_count": 86,
  "programs": [
    { "name": "人工智慧科技學程", "course_count": 33, "course_ids": ["364892", "364893"] }
  ]
}

{
  "classroom_count": 234,
  "classrooms": [
    {
      "id": "452",
      "name": "六教727(e)",
      "capacity": 50,
      "course_count": 12,
      "course_ids": ["364893"],
      "url": "https://aps.ntut.edu.tw/course/tw/Croom.jsp?format=-3&year=115&sem=1&code=452"
    }
  ]
}

學程只有中文名稱、沒有代碼，所以不另外開明細檔。

教室容量

capacity.json 是教室代碼 → 容量的對照表，各學期的 classrooms.json 每筆也 直接帶 capacity 欄位，不必再查一次。

容量與學期無關。 實測 Croom.jsp 的 year / sem 參數只影響使用率與 週課表，容量欄位不受影響 —— 打一個不存在的學年度（year=199）仍然回傳 正確容量。所以學校不保留歷史容量：教室改建後，所有學期都會顯示新值。

因此各學期 classrooms.json 的 capacity 反映的是最近一次觀測值， 不是那個學期當時的容量。抓不到時是 null，不是 0。

每月重抓一輪，capacity.json 的 checked_at 是該筆最後一次確認的時間。

約半數教室沒有座位數。 全量實測 445 間裡有 216 間查得到（48.5%）， 其餘 229 間學校根本沒登記 —— 那格連同旁邊的使用率欄位一起是空白的， 打四個不同學年期（115-1 / 110-1 / 105-1 / 199-1）都一樣。這種 null 是 永久且正確的，不是抓取失敗。

分佈不是隨機的，一般教學大樓幾乎都有、研究與系館幾乎都沒有：

館別	有容量	館別	有容量
先鋒	18/18	綜科	15/82
六教	17/17	土木	2/11
四教	10/12	五教	1/10
二教	16/20	紡織	0/9
三教	34/44	化工	2/8

已知容量的 216 間範圍是 10～420，中位數 50。

「原本有值、這次讀不到」會保留舊值。 座位數不會無聲消失 —— 改建 會改變數字，不會把數字變成空白。所以那種情況一律保留舊值、更新 checked_at、並在 errors.json 記一筆；比例超過門檻時整批不發布， 讓 workflow 重試。這是為了擋掉「學校改版讓 216 間同時歸零」這種 靠事後看資料分辨不出來的災難。

115-1/schedule.json

{
  "periods": [{ "code": "1", "start": "08:10", "end": "09:00" }],
  "days": [
    {
      "day": 3,
      "day_name": "三",
      "periods": [
        { "code": "2", "course_count": 118, "course_ids": ["361345", "361351"] }
      ]
    }
  ]
}

periods 已依 1–9 → N → A–D 排好，不是字典序（字典序會把 A 排到 9 前面）。 沒有上課時間的課（體育、班週會）不會出現在這裡。

---

欄位說明

時間

time_slots 每個元素代表一天。day 是 0=日、1=一 … 6=六， periods 是節次代碼，對應時間查 meta.json 的 periods。 沒有上課時間的課 time_slots 是空陣列。

必選修

required 是布林值，requirement_type 是完整類別：

符號	required	requirement_type
○	true	部訂共同必修
△	true	校訂共同必修
☆	false	共同選修
●	true	部訂專業必修
▲	true	校訂專業必修
★	false	專業選修

注意 ★ 和 ☆ 都是「選修」，兩者差別在共同 / 專業，不是必 / 選。 原始資料該欄空白時 required 是 null，不是 false。

授課語言

language 空白（null）代表中文授課，不是「未知」—— 學校只在非中文的課填這一欄。115-1 全校的實際值只有 "英語"（488 門） 與 "中英雙語"（11 門）兩種，其餘 2,218 門都是 null。

所以「找全英語授課」的條件是 language === "英語"， 「找中文授課」是 language === null。

空值

原始頁面用全形空白 　(U+3000)表示「沒有這個欄位」， 輸出時一律正規化成 null（陣列欄位則是 []）。

---

schema_version 與相容性承諾

每個 JSON 檔的頂層都有 "schema_version"。目前是 3。

• 新增欄位、新增端點不會升版。 請用「忽略不認得的欄位」的方式寫你的程式。
• 移除欄位、改欄位型別、改欄位語意會升版，並在此處說明。
• 升版時舊版路徑不保證保留 —— 這是免費的靜態檔案服務，請鎖定你測試過的版本號， 發現 schema_version 變了就先檢查再上線。

v3（2026-09-05）

只影響教學大綱，把 v2 沒做完的那半件事做完。

改動	影響
{semester}/syllabus/{課號}.json 不再有 fetched_at	要知道何時抓的，讀 syllabus.json 的 fetched[學期][課號].at
同一個檔新增 content_hash	加欄位，不影響既有使用端
syllabus.json 的 fetched[學期][課號] 從字串變成物件	原本是抓取時間字串，現在是 {"at": ..., "hash": ...}
syllabus.json 新增 frozen 區塊	已補完的歷史學期只留門數，逐課狀態不再保留

為什麼要動： 跟 v2 拿掉 generated_at 完全同一個理由，只是漏了大綱這一塊。 fetched_at 每次抓取都變，一天兩班、每班 1,909 份大綱，即使內容一個字都沒改， git 也會收下 1,909 個新 blob。改成比對內容雜湊之後，沒變就不重寫那個檔， 配合 keep_files: true，遠端那份原封不動留著。

v2（2026-09-04）

為了容納 90 學年度起的歷史資料而做的兩個改動。兩個都會影響既有使用端：

改動	影響
頂層 index.json 只涵蓋最新兩個學期（原本是全部）	要更舊的學期改讀 {semester}/index.json；新增 covers 欄位明講涵蓋範圍
generated_at 只留在 meta.json 與 errors.json	其他檔案不再有這個欄位。要知道某學期何時產生，讀 meta.json 的 semesters[].generated_at

為什麼要動： 50 個學期全塞進一個 index.json 會膨脹到數十 MB； 而每個檔都帶時間戳的話，每次抓取後所有檔案內容都會變，發布時等於整包重推 —— 以歷史資料的量級來說那是每天好幾 GB 的無謂流量。 時間戳集中在 meta.json 粒度也更正確：一個學期的所有檔案本來就是同一次產生的。

更新頻率與學年期

workflow	頻率	台灣時間
crawl	每 4 小時	00、04、08、12、16、20 時
syllabus	一天兩次	09、21 時
capacity	每月一次	1 號 10 時(排在同一天的整包重建之前)
crawl（整包重建）	每月一次	1 號 14 時
backfill	只手動	補歷史學期的課表與大綱

GitHub Actions 的排程常延遲 2～4 小時，上表只是排程時間。 meta.json 的 generated_at 是該次產生的實際時間，請以它為準。

學年期是自動偵測的

爬蟲每次啟動會先讀學校首頁，看目前掛了哪幾個「上課時間表」入口， 再決定要抓哪些學期 —— 學年期沒有寫死在任何地方。 115-1 過完換 115-2、再換 116-1，程式與 workflow 都不用改。

• 最新學期每次都重抓（選課期間資料每天在動）
• 其他學期預設 24 小時才重抓一次（過去的學期幾乎不再變動， 每 4 小時全部重抓只是白白增加學校的負擔）
• 學校首頁下架的舊學期資料會留著，只是不再更新

所以 meta.json 的 semesters 會越積越多。要最新的那個就讀 latest。

歷史學期只抓一次

首頁只掛最近兩個學期，但 Subj.jsp?format=-2&year=&sem= 不理會首頁 —— 90 學年度起的資料都還在，而且版面 25 年沒變（一樣是 23 欄，教師與教室 一樣是帶代碼的連結），所以同一套解析器直接吃得下。

這些歷史學期是一次性回補下來的，之後不會再重抓（過去的學期資料不會變）。

每月一次的整包重建

每月 1 號會整包重新發布一次。班級或教師從學校系統消失後， 它們的舊明細檔會在那時從線上移除 —— 在那之前可能還查得到。

---

資料範圍與已知限制

• 只涵蓋課程查詢系統的「上課時間表」（Subj.jsp?format=-2 那棵樹）。 該系統每個學期只提供這一個上課時間表入口，因此這棵樹爬完即無遺漏。 暑期課程（Summer.jsp）、學程查詢、教室使用情形不在本專案範圍。
• 教學大綱有抓（見上），一天全量更新兩次，所以最多落後半天。 確切時間看 syllabus.json 的 fetched[學期][課號].at； 老師最後修改的時間是該檔的 updated_at。 越早的學期有大綱的課越少（96 學年度以後約七成，90～92 學年度約 1%）。
• 學程查詢系統不在範圍內，所以查得到「無人機微學程有哪些課」， 查不到「修完幾門才算完成該微學程」。
• 沒有進修部的獨立入口。 實地確認過總覽頁的 60 個單位裡沒有進修部， 抽查機械系、資工系的班級列表也沒有夜間班。若學校另有進修部課表， 不在 aps.ntut.edu.tw/course/tw/ 底下。
• name_en 永遠是 null。 課程列表頁與教學大綱頁都沒有英文課名， 目前無資料來源。欄位保留是為了維持 schema 穩定。
• 課號在一個學期內唯一，但「合開」的課各班級是不同課號。 同一個課號若出現在多個班級頁（通識、體育、校院級課程很常見）， 會合併成一筆，classes / class_ids / department_ids 列出全部。 115-1 有 110 門課跨多個系所。 但「合開」不是這種情況 —— 例如「數位影像處理」在資工四是 364893、 在資工所是 364899，notes 都寫「資工四和資工所合開」， 它們是兩筆獨立資料。不要假設「同一門課 = 同一個課號」， 要判斷是否同一門課請一併看 notes。
• enrolled / withdrawn 是原始頁面的「人」「撤」欄位，會隨選課進度變動， 只反映抓取當下的狀態。歷史學期的值是該學期結束後很久才抓的， 等於是最終定案的數字，不代表當年選課期間的即時人數。 想看變動過程請用 enrollment.json（只有開始記錄之後的學期才有）。 quota 是 enrolled 的舊名，已棄用但保留。
• 歷史資料到 90 學年度為止。 實測 85-1 只剩零星幾個單位、80-1 以前是空頁， 不是抓取失敗而是系統本來就沒有。各學年度實際抓到幾個單位見 meta.json。
• 舊學期的系所代碼與現在不一定對得起來。 系所會改名、合併、裁撤， 代碼也會被回收。跨學期比較時請以各學期自己的 departments.json 為準， 不要拿 115-1 的代碼表去套 95-1。
• 教學大綱是一天全跑兩次抓下來的，updated_at 是老師在學校系統上最後 修改的時間（已轉成 UTC）。看不懂的日期格式會原樣保留，不保證是 ISO 8601。 沒有 syllabus_url 的課（跨校選課那類）不會有 {semester}/syllabus/ 檔案。

---

免責聲明

本專案為非官方個人專案，與國立臺北科技大學無隸屬關係。

資料以自動化方式蒐集自北科大課程查詢系統， 可能因學校改版、網路異常或解析錯誤而不完整或過時。 選課、抵免、畢業學分等一切事項請以學校公告與課程系統當下顯示的內容為準， 因使用本資料造成的任何損失，本專案不負責任。

若校方認為本專案造成困擾，請開 issue 告知，我會立即停止。

---

授權

程式碼採 MIT License。

資料本身著作權屬國立臺北科技大學，本專案僅為格式轉換與再發布。 使用資料時請標註來源為「國立臺北科技大學課程查詢系統」。

---

開發

環境

python -m venv .venv
.venv/Scripts/activate        # Windows
pip install -r requirements-dev.txt

執行

python -m crawler.main --out data/                       # 自動偵測學年期
python -m crawler.main --year 115 --sem 1 --out data/    # 指定學年期
python -m crawler.main --out data/ --dept 59 --pretty    # 開發用,只抓一個系所
python -m crawler.main --out data/ --no-cache --delay 1.5

# 回補歷史學期(已經抓過的會自動跳過,可以分批續跑)
python -m crawler.main --out data/ --years 90-114 --max-semesters 12

參數	說明
--year / --sem	指定學年期。要嘛都給，要嘛都不給；都不給就自動偵測
--refresh-after HOURS	非最新學期隔多久才重抓（預設 24 小時）
--all-semesters	首頁列出的每個學年期都重抓，忽略 --refresh-after
--years FROM-TO	回補模式：抓這個學年度範圍內尚未抓過的學期，例 --years 90-114
--max-semesters N	這次最多抓幾個學期（回補分批用）
--out DIR	輸出目錄，預設 data/
--dept CODE	只抓指定系所（可重複）。輸出會是不完整的資料集
--delay	每次請求後的延遲秒數，下限 0.5
--no-cache	略過 .cache/，強制重新抓取
--pretty	輸出縮排過的 JSON（檔案會變大）
--with-syllabus	順便抓教學大綱（一門課一頁，很慢，預設關閉）
--max-syllabus N	這次最多抓幾頁大綱，預設 0 = 不限（全校一輪約 38 分鐘）
--syllabus-refresh-after H	同一門課的大綱隔多久重抓，預設 6 小時（配合一天兩班各全跑一輪）。只對最新學期有效，歷史學期一律只補沒抓過的
--with-capacity	順便抓教室容量（座位數），每月重抓一輪，預設關閉
--max-capacity N	這次最多抓幾間教室，預設 0 = 不限（全部約 445 間、9 分鐘）
--capacity-refresh-after H	同一間教室的容量隔多久重抓，預設 480 小時（20 天）
--run-summary PATH	把這次跑了什麼寫成側寫檔，給 crawler.runlog 記進 runs.json
--log-level	記錄層級，預設 INFO。抓不到東西時開 DEBUG 看實際打了哪些 URL

測試

pytest -q

測試完全離線，全部對 tests/fixtures/ 裡的真實 HTML 樣本斷言。 tests/conftest.py 有一道安全網，任何測試只要發出真實 HTTP 請求就會直接失敗。

解析器測試刻意寫得很細 —— 學校改版時它們會先紅， CI 就不會把解錯的資料發布出去。

抓取禮儀（請勿放寬）

• 單執行緒，不使用 threading / asyncio / multiprocessing 平行抓取
• 每次請求後強制 sleep，預設 1.0 秒，下限 0.5 秒（crawler/http.py 硬性限制）
• workflow 設了 concurrency 群組，不會有兩個 job 同時抓
• 非最新學期預設 24 小時才重抓一次，不會每 4 小時把所有學期重掃一遍
• 歷史學期（回補下來的）抓過就永久跳過，25 年的資料只會被抓一次
• User-Agent 帶專案網址，方便校方辨識與聯絡
• 對方連不上時整個停手：連續 3 個網址重試到底仍然失敗，就判定學校端 目前不可用，本次執行剩下的請求一律直接放棄、不再重試

課程網站抓太快很容易被封鎖。這些限制不是效能問題，是能不能長久運作的問題。

重試、逾時與容錯分層的設計理由見 reference.md。

架構

crawler/
  config.py         # 常數(base URL / schema 版本 / 延遲 / User-Agent)
  http.py           # 全專案唯一對外出口:限速、快取、重試、UTF-8 解碼
  models.py         # 輸出 schema 的 dataclass 定義
  periods.py        # 節次代碼對照與解析
  parse_util.py     # 解析器共用工具
  parse_semester.py # 解析 course.jsp — 目前有哪些學年期(純函式)
  parse_dept.py     # 解析 format=-2 / -3(純函式,不連網)
  parse_course.py   # 解析 format=-4(純函式,不連網)
  parse_syllabus.py # 解析教學大綱頁,並判斷課號還在不在(純函式)
  parse_croom.py    # 解析教室頁的容量(純函式)
  output.py         # 把 CrawlResult 寫成各維度的 JSON
  main.py           # CLI:選學期、抓取流程、去重
  runlog.py         # CLI:把一次 workflow 執行的結果記進 runs.json

tests/              # 全離線,對 tests/fixtures/ 的真實 HTML 樣本斷言
.github/workflows/  # crawl(每 4 小時)、syllabus(一天兩班)、
                    # capacity(每月一次,教室容量)、backfill(手動回補)、
                    # test(每次 push)
web/                # 發布到 gh-pages 根目錄的頁面,整個目錄由 workflow 複製過去
                    # index.html(說明)、status.html(爬蟲狀態)、
                    # errors.html(抓取失敗)、changes.html(課程異動)、
                    # 加上共用的 style.css 與 app.js

解析器一律是純函式：吃 HTML 字串 → 吐 dataclass，不發網路請求。 所有網路存取都集中在 http.py，限速與快取的規則只要在那裡守住就守住了。

要改這個 repo 的話，硬性規定、實測過的站台特性與決策紀錄見 reference.md。