免费节假日查询接口整理与使用教程说明本文基于公开文档与社区文章整理未对每个接口做真实请求实测接口可用性、字段含义与限流策略以公开文档为准集成前请自行验证。文中各来源完全平级仅按公开文档整理接入写法未返回真实业务数据。写在前面业务里经常要判断「今天是不是节假日 / 调休补班日」「某年有哪些法定假期」。节假日由国务院每年公布无法靠公式推算所以一般要依赖现成接口或离线数据。网上能找到的节假日查询接口不少写法与口径差异很大有的需要 Key、有的完全匿名有的覆盖调休补班、有的只给公共假日有的是国内官方口径、有的是国际口径。本文把公开文档里能找到、且能写出「请求地址 参数 返回示例」的源整理出来按源逐一给出接入写法供按需取舍。通用提醒多数免费接口由个人或社区维护存在限流、节点抖动甚至停服的可能。无论选哪个都建议加一层本地缓存一年数据基本固定拉一次存库即可并对远程失败做降级。1. 接口总览接口请求地址说明是否需 Key协议 / 格式国内调休口径来源类型万维易源 · 节假日查询894894-4 接入点按年查全年需免费 appKeyHTTPS / JSON含调休补班第三方平台开源工具箱 · jiarijiari 接口传参 d 指定年月日无需HTTP / 文本·JSON含0/1/2 编码社区开源提莫的神秘小站按年 / 按日两个查询接口无需HTTPS / JSON含个人公益APIHubsholiday/get 接口参数最丰富无需HTTPS / JSON含字段区分社区开源jiejiariapiv1 系列接口节假日 / 周末 / 工作日 / 单日判断匿名可用 / 可选 KeyHTTPS / JSON含社区开源Nager.DatePublicHolidays 接口按国家代码查询无需HTTPS / JSON不含调休国际开源天行数据 · 节假日139139 接口按年 / 月 / 日期范围查询需 KeyHTTPS / JSON含商业平台appKey / 平台密钥的获取以各平台官方文档为准相关接入凭证请在对应平台注册后获取本文不再列出具体地址。2. 万维易源 · 节假日查询894第三方平台接口国务院发布安排后一般一周内更新。提供 3 个接入点894-4假日列表按年查全年894-6节假日查询按日查可选返回节日简介894-7调休日列表查询查某年所有调休日请求方式 POST / GET返回 JSON统一包裹showapi_res_code/showapi_res_error/showapi_res_body业务数据在showapi_res_body内。请求示例按年查全年接口地址请以其官方文档为准curl -X POST 易源894-4接口地址?appKeyYOUR_APPKEY \ -H content-type: application/x-www-form-urlencoded \ -d year2026返回示例{ showapi_res_code: 0, showapi_res_error: , showapi_res_id: ce135f6739294c63be0c021b76b6fbff, showapi_res_body: { ret_code: 0, data: [ { holiday: 劳动节, holiday_remark: 5月1日周四至5日周一放假调休共5天。4月27日周日上班。, inverse_days: [20250427], end: 20250505, begin: 20250501 } ] } }注意事项需领取免费 appKey不带 key 时返回结构化错误非 5xx说明服务在线。data[]含begin/end/holiday/holiday_remark/inverse_days调休补班日2021 年之后才有值。免费但设有调用档次限制正式接入前请确认当前档位额度。3. 开源工具箱 · jiari无需 Key格式极简适合快速判断单日状态或批量拉全年。请求参数dYYYY全年YYYYMM某月YYYYMMDD单日开始-结束区间如20260101-20260107返回文本数字0工作日、1休息日周末、2法定节假日。请求示例# 查全年返回 JSON 数组形式的状态编码 curl 开源工具箱jiari接口地址?d2026 # 查单日返回 2 表示 2026-05-01 是法定节假日 curl 开源工具箱jiari接口地址?d20260501注意事项返回的是极简编码需自行做 0/1/2 → 文案的映射。无官方 SLA适合个人项目与内部工具。4. 提莫的神秘小站个人维护的开源公益接口数据基于国务院通知整理无需 Key。提供按年查询与按日查询两类接口。返回示例按年节选{ code: 0, holiday: { 2026-01-01: { date: 2026-01-01, name: 元旦, holiday: true, wage: 3, rest: 1 }, 2026-05-01: { date: 2026-05-01, name: 劳动节, holiday: true, wage: 3, rest: 1 } } }请求示例带 User-AgentPython接口地址请以其官方文档为准import requests # timor.tech 按年查询接口地址请以其官方文档为准此处用占位符代替真实地址 TIMOR_URL timor.tech节假日接口地址/year/2026 r requests.get(TIMOR_URL, headers{User-Agent: Mozilla/5.0}, timeout15) data r.json() for k, v in data.get(holiday, {}).items(): if v.get(holiday): print(v[date], v[name])注意事项实测不带请求头会被拦截403调用务必带上User-Agent。稳定性依赖个人运维建议配合本地缓存使用。5. APIHubs无需 Key查询参数最丰富可按年 / 月 / 日 / 星期 / 是否工作日 / 是否法定节假日 / 是否调休等组合筛选。主接口为 holiday/get。常用参数均为可选多条件之间为「与」关系year年份month月份date日期workday是否工作日含调休上班日weekend是否周末holiday节假日枚举holiday_overtime调休枚举holiday_legal是否法定节假日三倍工资holiday_recess是否假期节假日节日是否放假cn是否返回中文可读字段默认返回数字与枚举码便于逻辑判断field指定返回字段、page/size分页返回示例item节选常用字段{ code: 0, msg: ok, data: { page: 1, size: 10, total: 365, list: [ { year: 2021, month: 202101, date: 20210101, week: 5, weekend: 2, workday: 2, holiday: 22, holiday_overtime: 10, holiday_today: 1, holiday_legal: 1, holiday_recess: 1, year_cn: 2021年, date_cn: 2021年01月01日, holiday_cn: 元旦 } ] } }请求示例# 查全年日历含周末size 调大一次拿全 curl APIHubs holiday/get接口地址?size500year2021注意事项默认返回数字日期与枚举码适合做逻辑判断开启cn参数会附带可视化中文。共享节点注意限流生产环境做好缓存。6. jiejiariapi提供节假日 / 周六日 / 工作日 / 单日判断四类接口文档清晰匿名即可调用。请求示例单日判断接口地址请以其官方文档为准curl jiejiariapi v1单日判断接口地址?date2026-01-01返回示例全年 / 单日节选{ 2026-01-01: { date: 2026-01-01, name: 元旦, isOffDay: true } }{ is_holiday: true, holiday: { date: 2026-01-01, name: 元旦, isOffDay: true } }注意事项免费匿名 50 次/天、带 Key 100 次/天。免费版走海外 CDN国内访问可靠性不保证仅限个人测试学习。7. Nager.Date免费开源的国际节假日 API覆盖包括中国CN在内的多国适合跨境 / 多地区场景。按国家代码查询的接口为 PublicHolidays。返回示例中国节选[ { date: 2026-01-01, localName: 元旦, name: New Years Day, countryCode: CN, types: [Public] }, { date: 2026-05-01, localName: 劳动节, name: Labour Day, countryCode: CN, types: [Public] } ]请求示例curl Nager.Date PublicHolidays接口地址/2026/CN注意事项返回的是各国「法定公共假日」**不含调休补班周末上班**口径。国内使用需自行叠加周末与调休规则适合做国际日历补充。8. 天行数据 · 节假日139商业平台接口需 Key。支持按年 / 按月 / 按日期范围 / 多日期批量查询返回维度较广。请求参数type查询类型1按年、2按月、3按日期范围、多个日期用英文逗号分隔批量date日期格式随 type 变化如2020、2020-10、2020-11-1~2020-11-10返回关键字段daycode日期类型0工作日、1节假日、2双休日、3调休日上班isnotwork是否休息0上班、1休息wage当日法定工资倍数周末 2 倍法定节假日 3 倍请求示例需携带平台密钥接口地址请以其官方文档为准curl 天行数据139接口地址?type1date2026keyYOUR_KEY注意事项需注册并获取平台密钥有调用额度限制。按年查询只返回中国官方节假日按月查询未指定日则默认该月第一天到最后一天范围查询起点终点用~分隔总日期数不超过 31 天。横向对比事实对照维度万维易源 894bitefutimor.techAPIHubsjiejiariapiNager.Date天行数据是否需 Key需免费 appKey无需无需无需匿名可用无需需 Key返回格式JSON文本/JSONJSONJSONJSONJSONJSONHTTPS是否是是是是是国内调休含含含含含不含含主要限制档位额度无官方 SLA需带 UA、个人运维共享节点限流匿名 50/天国际口径需 Key、额度各源特点不同易源偏平台稳定、bitefu 偏极简免 Key、APIHubs 参数维度全、Nager.Date 覆盖国际按自身成本与精度需求取舍即可没有全能最优解。生产环境参考实现多源降级下面是一段参考实现把所有源列为对等节点按「发请求并落业务字段、失败切换下一源」串联。各源请求地址请以其官方文档为准文中以占位符代替排序交由调用方决定未做真实请求实测仅演示降级思路。import requests # 各源接口请求地址请以其官方文档为准以下用占位符代替真实地址 BASE { showapi: 易源894-4接口地址, bitefu: 开源工具箱jiari接口地址, timor: timor.tech节假日接口地址, apihubs: APIHubs holiday/get接口地址, jiejiari: jiejiariapi v1接口地址, nager: Nager.Date PublicHolidays接口地址, } # 各源的归一化解析函数输入原始响应输出 {date, is_holiday, is_workday, name, is_overtime} def query_showapi(year, appkey): r requests.post( BASE[showapi], params{appKey: appkey}, data{year: year}, timeout10, ) body r.json()[showapi_res_body] out [] for item in body.get(data, []): out.append({ date: item[begin], is_holiday: True, is_workday: False, name: item.get(holiday), is_overtime: False, }) return out def query_bitefu(year): r requests.get(BASE[bitefu], params{d: year}, timeout10) return r.json() # 0/1/2 编码需自行映射 def query_timor(year): r requests.get(f{BASE[timor]}/year/{year}, headers{User-Agent: Mozilla/5.0}, timeout10) return r.json().get(holiday, {}) def query_apihubs(year): r requests.get(BASE[apihubs], params{year: year, size: 500}, timeout10) return r.json().get(data, {}).get(list, []) def query_jiejiari(year): r requests.get(f{BASE[jiejiari]}/holidays/{year}, timeout10) return r.json() def query_nager(year): r requests.get(f{BASE[nager]}/PublicHolidays/{year}/CN, timeout10) return r.json() # 按优先级串联任一源成功即用失败降级下一源 SOURCES [query_apihubs, query_timor, query_jiejiari, query_bitefu, query_nager] def get_holidays(year, appkeyNone): for src in SOURCES: try: data src(year) if src is not query_showapi else query_showapi(year, appkey) if data: return data except Exception: continue return [] if __name__ __main__: # 演示用途未实测生产环境请加本地缓存与限速 print(get_holidays(2026))踩坑清单调休补班周末上班口径不一致Nager.Date 为国际口径、不含调休国内使用务必叠加周末与调休规则。timor.tech 不带User-Agent会被 403 拦截调用前确认请求头。免费接口限流差异大jiejiariapi 匿名 50 次/天、bitefu 无 SLA、APIHubs 共享节点生产环境务必加缓存。跨年切换风险次年数据通常年底前才公布元旦前后建议提前验证避免读到旧年数据。字段命名不统一isOffDay/daycode/workday/weekend含义各不同接入时先对齐语义再落库。易源等「免费服务」仍需 appKey且有调用档次限制勿按「完全免费无 key」理解。附录补充说明APIsBO 也提供中国节假日查询接口接口列表含/date/:date、/batch、/year/:year但公开文档未给出返回示例且需注册后查看鉴权方式接入前请到对应平台确认。网上还流传若干同类接口多需自备 Key 或写法不完整未逐一展开集成前请自行核对官方文档与可用性。所有接口的数据源头均为国务院办公厅每年发布的节假日安排更新时效以各服务提供方为准。常见问题 FAQ问免费节假日接口需要 Key 吗答不一定。万维易源 894、天行数据需要 Keybitefu、timor.tech、APIHubs、jiejiariapi、Nager.Date 均可匿名调用但匿名通常有额度或稳定性限制。问哪个接口返回最全、含调休补班答万维易源 894、APIHubs、jiejiariapi、timor.tech、bitefu 都覆盖国内调休补班口径Nager.Date 是国际公共假日口径不含调休需自行叠加规则。问只想快速判断某天是不是节假日用哪个最简单答bitefu 的 jiari 接口最简单传dYYYYMMDD返回 0/1/2 编码即可判断无需 Key。问需要按月、按周、按是否调休精细筛选用哪个答APIHubs 的 holiday/get 参数覆盖最全支持 year/month/date/workday/weekend/holiday_overtime 等组合筛选。问做跨境或多国家日历选哪个答Nager.Date 覆盖多国公共假日按countryCode查询适合国际场景但需注意它不含中国调休规则。问timor.tech 调用返回 403 怎么办答需带上User-Agent请求头否则会被拦截建议配合本地缓存降低对个人维护节点的依赖。问免费接口的限流一般是多少答jiejiariapi 匿名 50 次/天、带 Key 100 次/天bitefu、APIHubs 多为共享节点无明确公开额度建议缓存 降级。问数据多久更新一次答国务院一般每年底发布次年安排万维易源等会在文件发布后约一周内更新免费社区接口更新时效略有差异跨年切换时建议提前验证。问生产环境怎么保证稳定答无论选哪个免费接口都建议加一层本地缓存一年数据基本固定拉一次存库即可并对远程失败做多源降级。问返回字段里的 daycode / isOffDay / workday 都是什么意思答各接口字段命名不同天行用daycode0工作/1节假/2双休/3调休jiejiariapi 用isOffDayAPIHubs 用workday/weekend枚举接入时先对齐语义再落库。问万维易源 894 有哪几个接入点答三个——894-4假日列表按年、894-6节假日查询按日、894-7调休日列表查询按年均需 appKey返回 JSON。问本文里的接口都实测过吗答没有。本文基于公开文档与社区文章整理未对每个接口做真实请求实测接口可用性、字段与限流以公开文档为准集成前请自行验证。