台灣國定假日 API：免費 JSON 端點，含補班日、農曆與請假計算

如果你做過需要判斷「這天要不要上班」的系統，大概都遇過同一件事：政府開放資料的格式每年不太一樣，自己維護一張假日表又很容易漏掉補班日。

所以我做了一個 JSON API，網址直接開就有資料，不用申請金鑰、不用註冊。這篇把端點、欄位和串接方式一次寫清楚。

直接拿資料

所有資料都放在 jsDelivr CDN 上，以 2026 年為例：

把網址裡的 2026 換成 2017 到 2026 的任何一年都可以。

回傳格式

每一天都是這樣的一個物件：

{
  "date": "20260101",
  "week": "四",
  "isHoliday": true,
  "description": "開國紀念日",
  "lunar": {
    "date": "冬月十三",
    "festivals": [],
    "solarTerm": null
  }
}

holidays.json 只留真正的國定假日，不含一般週末，2026 年是 22 筆。

串進你的程式

JavaScript：

const holidays = await fetch(
  "https://cdn.jsdelivr.net/gh/imsyuan/taiwan-holidays/data/2026/holidays.json",
).then((r) => r.json());

const isHoliday = (ymd) => holidays.some((day) => day.date === ymd);
console.log(isHoliday("20260101")); // true

PHP：

$url = 'https://cdn.jsdelivr.net/gh/imsyuan/taiwan-holidays/data/2026.json';
$calendar = json_decode(file_get_contents($url), true);

// Index by date so lookups don't scan the whole year.
$byDate = array_column($calendar, null, 'date');
$needsWork = $byDate['20260101']['isHoliday'] === false;

Python：

import requests

calendar = requests.get(
    "https://cdn.jsdelivr.net/gh/imsyuan/taiwan-holidays/data/2026.json"
).json()

by_date = {day["date"]: day for day in calendar}
print(by_date["20260101"]["description"])  # 開國紀念日

要判斷某一天要不要上班，抓整年日曆的 2026.json 最省事：補班日在裡面已經是 isHoliday: false，不用自己跟另一份清單對。

讓 AI 直接算工作日

如果你的情境是「從今天起算 10 個工作日是哪天」「今年 5 天年假怎麼請最划算」，這些用 JSON 自己算很麻煩，所以另外做了一個 MCP server，部署在 Cloudflare Workers：

# Claude Code
claude mcp add --transport http taiwan-workday https://mcp.tw-holidays.gooliya.com/mcp

接上之後可以直接用中文問。目前有五個工具：算區間工作日數、從某天起算第 N 個工作日、查下一個補班日、請假最佳化、找出遊時段。日期一律用 YYYY-MM-DD。

想先看視覺化的日曆和請假攻略，可以直接開 tw-holidays.gooliya.com。

常見問題

要錢嗎？需要申請金鑰嗎？ 不用。資料是 GitHub 上的靜態 JSON，透過 jsDelivr 公開存取，沒有金鑰也沒有流量限制的申請流程。

涵蓋哪些年份？ 2017 到 2026 年。新年度的行政院行事曆公布之後才會補上，所以不會提前有明年資料。

資料多久更新一次？ 用 GitHub Actions 定期從政府開放資料同步，修正也是直接進版本庫。

2026 年為什麼查不到補班日？ 因為 2026 年的行事曆沒有安排補班，makeup-workdays.json 回傳的是空陣列。這是正確結果，不是 API 壞掉。

可以用在商業專案嗎？ 可以，專案採 MIT 授權。

這個專案是怎麼做出來的

第一版是用 Vibe Coding 做的：我只描述要什麼，程式碼交給 AI 寫。我告訴它我要台灣假日的 JSON API、資料來自政府開放資料，接著再一項一項補需求——我要農民曆、我要中英雙語、我要補班日，最後讓它補上 GitHub Actions 定期更新，設定 jsDelivr 對外。

工程師的價值本來就不在打字，而是在設計架構、定義需求、驗收品質。AI 幫我打字，這個專案從想法到上線只花了幾個小時，省下來的時間可以多陪小孩一點。

下一步

如果你只是要判斷某天放不放假，抓 2026.json 這一個檔案就夠了，不用接其他端點。要算工作日或請假，再接 MCP server。

原始碼在 GitHub：imsyuan/taiwan-holidays。發現資料有錯可以直接開 issue。