节假日 API · 免费法定节假日接口与调休 JSON

免费的法定节假日接口：一个地址取一整年的放假日与调休上班日，返回 JSON，支持跨域，不用注册、不用申请密钥；另有按日期查询的接口，直接告诉你这一天是法定节假日、调休上班日、周末还是普通工作日。数据依据国务院办公厅历年放假通知，从 2016 年起，下一年的安排公布后自动更新。页面上能在线试请求、复制 curl、JavaScript、Python 调用示例；不写代码的人也能把放假和调休一键订阅到苹果、谷歌、Outlook 日历。

怎么用

这一页是 Hi8 的节假日 API说明，也是一个能在线试请求的小工具。打开页面，最上面那张卡片就是单日接口对今天的真实返回：今天上班还是休息、为什么。

三个接口地址

全部是 GET 请求，返回 JSON，地址里把 YYYY 换成年份、YYYY-MM-DD 换成日期：

• 按年取：https://hi8.com/api/holiday/YYYY.json，返回这一年全部法定节假日放假日和调休上班日，是最常用的那个，接进自己系统时一年取一次就够。
• 按日期取：https://hi8.com/api/holiday/date/YYYY-MM-DD.json，直接告诉你这一天是法定节假日、调休上班日、周末还是普通工作日，适合「今天上不上班」这类提醒和机器人。
• 年份清单：https://hi8.com/api/holiday/years.json，列出接口里有哪些年份、每一年的安排公布了没有、最近一次同步的时间。

不用注册、不用密钥、允许跨域，浏览器前端和服务端都能直接调。另有一份 OpenAPI 描述 https://hi8.com/api/holiday/openapi.json，可以导入 Postman、Apifox，或交给代码生成器、AI 助手直接读。

订阅到手机日历

不写代码也能用：日历订阅地址 https://hi8.com/api/holiday/cn.ics 把 2016 年以来的每个假期做成一条全天事件，调休上班日单独一条。苹果手机、苹果电脑和 Outlook 点页面上的「一键订阅」即可；谷歌日历在网页版「其他日历 → 通过网址添加」里粘贴地址。日历软件会定期自己刷新，明年的放假安排公布后会自动出现在日历里。

在线试一下

在「在线试一下」那一栏选接口，按年取就选年份，按日期取就选日期，点「发送请求」，下面会显示完整的请求地址、HTTP 状态码和返回的 JSON；按年取时还会顺带算出这一年放假几天、调休上班几天。返回的 JSON 可以一键复制，也可以点「新窗口打开」看原始返回。

调用示例

「调用示例」那一栏有 curl、JavaScript、Python 三段能直接跑的代码，地址里的年份和日期已经按今天填好。Python 那段在请求头里带了 User-Agent，这一行别删：Python 自带的 urllib 用默认标识会被拦下，返回 403。JavaScript 那段演示了最常见的用法：取一整年的数据，做成两个集合，再写一个判断某天是不是工作日的函数——先看是不是调休上班日，再看是不是法定节假日，最后才看星期几。这个顺序不能反：调休上班日多半是周末，只看星期会判错。

使用条件

免费，请在用了这份数据的页面上署名并链接到本页。页面底部有一行现成的署名代码，复制后贴进页脚即可。内部系统、命令行脚本这类没有公开页面的用法，在项目说明或代码注释里注明数据来源就行。

怎么看结果

按年取的字段

没出现在 days 里的日子按普通星期算：周一到周五上班，周六周日休息。所以判断某一天时，先查 days，查不到再看星期几。

元旦的放假安排常常跨年，比如上一年的 12 月底就开始放。接口按日期所在的年份归档：上一年 12 月底那一两天出现在上一年的返回里，不会混进下一年。

按日期取的字段

状态码

• 200：正常返回。还没公布的年份也是 200，看 published。
• 400：日期写错了，比如二月三十日。
• 404：年份超出范围（早于 2016 年或晚于明年），返回里带可查的最早和最晚年份。
• 403：多半是 Python 自带的 urllib 没带 User-Agent，加上即可。
• 429：一分钟内请求超过 60 次，按 Retry-After 等一分钟再试。

常见问题

数据多久更新一次？

后台每年 9 月到 12 月每天核对一次，其余月份每周核对一次。国务院办公厅公布下一年的安排后，通常一两天内就能从接口取到；今年、明年和年份清单缓存一小时，已经过去的年份缓存一天。数据进库前要过一遍校验：日期不合法、条目重复、数量异常的年份整年丢弃，保留旧数据；拉到空数据也不会覆盖已有的安排。

这些数据我自己就能整理，为什么用接口？

每年手动抄一遍放假通知容易漏掉调休上班日，跨年的元旦更容易算错年份；而且下一年的安排什么时候公布不固定，靠人盯总会晚。接口把 2016 年以来每一年的数据整理成同一种格式，公布后自动更新，程序里写一次就不用管了。

能不能离线用？

能。按年取的返回只有几 KB，可以每年取一次存成本地文件，或者打包进自己的程序。只是记得在明年的安排公布后再取一次。

想看结果而不是写代码？

直接用站里的几个工具页，数据是同一份：

• 算两个日期之间有几个工作日、往后推 N 个工作日，用工作日计算器；
• 看今天、这个周末上不上班，用调休查询；
• 看今年每个假期放几天、哪天补班，用放假安排；
• 要一张带「休」「班」标记、能打印的全年表，用全年日历；
• 查农历、黄历和节日倒计时，用万年历。

原理与冷知识

法定节假日与调休是怎么来的

全体公民放假的节日及天数由《全国年节及纪念日放假办法》规定，每年具体哪几天放、哪个周末要补班，由国务院办公厅在上一年年底前后发通知安排。调休的做法是把相邻周末的休息日挪到节日旁边，拼成连续的长假，挪走的那天在别的日子补回来，于是有了「周六要上班」。具体以现行规定和当年通知为准。

为什么判断工作日不能只看星期

一年里通常有几天调休上班日落在周末，又有十几天法定假日落在周一到周五。只按星期判断，一年会错二三十天。程序里最稳的写法就是上面示例里的顺序：先查调休上班，再查法定放假，最后才看星期。

关于数据来源

接口的数据依据国务院办公厅历年发布的部分节假日安排通知，经开源项目 holiday-cn 整理；Hi8 每天同步、逐条校验后存进数据库，再按年、按日期两种形状提供出来。2016 年到 2023 年的安排是一次性导入的历史数据，之后的年份由后台自动同步。

English summary