非常好用的节假日查询接口 - 知乎 - 程序猿·D·安宇雨 DeepMind

非常好用的节假日查询接口 - 知乎

安宇雨 - 随手采集
2024-01-01 18:24:16
随手采集
0000-未整理-等待研究

概述

平时在开发的过程中经常会用到查询节假日的功能，但由于节假日是每年由国务院统一公布，我们无法通过计算获取节假日，所以一般需要我们手动来维护节假日。

网上有很多节假日查询的接口，但查询条件和返回结果并不是太理想，于是就自己写了个节假日查询接口并提供一个简单的页面。接口提供丰富的查询参数并且响应的字段可以自由定制。

快速开始

节假日查询的接口地址为：

https://api.apihubs.cn/holiday/get

直接访问接口地址会得到当前年份当前月份的整月数据，其中包含了详细的节假日信息

节假日查询的示例页面地址为：

http://www.apihubs.cn/#/holiday

在示例页面中会根据你选择的条件动态生成接口地址，然后可以直接点击浏览器中打开接口地址预览接口返回信息

参数

节假日查询接口提供了丰富的查询参数，所有参数都为可选参数，可灵活搭配使用，多个条件之间为&&的关系

参数中的日期格式均为PHP中的日期格式

field 用来指定返回结果包含的字段，多个使用英文逗号分隔枚举
year 用来指定要查询的年份，格式为 Y ,多个使用英文逗号分隔
month 用来指定要查询的月份，格式为 Ym ,多个使用英文逗号分隔
date 用来指定要查询的日期，格式为 Ymd ,多个使用英文逗号分隔
yearweek 用来指定要查询一年中的第几周，格式为 oW ,多个使用英文逗号分隔
yearday 用来指定要查询一年中的第几天，格式为 z ,多个使用英文逗号分隔
holiday 用来指定要查询的节假日，99为全部节假日，多个使用英文逗号分隔枚举
holiday_overtime 用来指定要查询的节假日调休（加班），99为全部调休，多个使用英文逗号分隔枚举
week 用来指定要查询的星期，多个使用英文逗号分隔枚举
workday 用来指定查询是否为工作日（包含调休在内需要上班的日子）枚举
weekend 用来指定查询是否为周末（星期六和星期日）枚举
holiday_today 用来指定查询是否为节日当天枚举
holiday_legal 用来指定查询是否为法定节假日（三倍工资）枚举
holiday_recess 用来指定查询是否为假期节假日（节日是否放假）枚举
lunar 用来指定年份、月份、日期、天数参数是否查询农历日期
cn 用来指定返回结果是否包含中文结果，默认返回的都是数字日期和枚举数字有利于逻辑判断不利于显示
page 分页页码
size 分页每页数量

响应

节假日查询接口的枚举功能是基于 php-enum 实现的统一格式响应

节假日查询接口响应始终为JSON数据格式，如下

{
    "code": "0",
    "msg": "ok",
    "data": ""
}

code 成功时始终为0，失败时为枚举值中的key
msg 成功时始终为 ok 失败时为枚举值中的value
data 成功时返回数据，失败时部分返回失败数据，如表单验证失败。
data.page 当前页码
data.size 当前每页数量
data.total 根据查询条件查到的总数量
data.list 节假日列表

data.list包含了节假日的详细信息，其中的所有字段都可以通过 field 参数进行按需使用

默认会返回数字日期和枚举码，这非常适合用来做逻辑判断。如下

{
    "year": 2021,
    "month": 202101,
    "date": 20210101,
    "yearweek": 202053,
    "yearday": 1,
    "lunar_year": 2020,
    "lunar_month": 202011,
    "lunar_date": 20201118,
    "lunar_yearday": 343,
    "week": 5,
    "weekend": 2,
    "workday": 2,
    "holiday": 22,
    "holiday_or": 22,
    "holiday_overtime": 10,
    "holiday_today": 1,
    "holiday_legal": 1,
    "holiday_recess": 1
}

当开启了cn查询参数，会将查取的字段名加上 _cn 后缀返回可视化的新，并同原字段一起返回。如下

{
    "year": 2021,
    "month": 202101,
    "date": 20210101,
    "yearweek": 202053,
    "yearday": 1,
    "lunar_year": 2020,
    "lunar_month": 202011,
    "lunar_date": 20201118,
    "lunar_yearday": 343,
    "week": 5,
    "weekend": 2,
    "workday": 2,
    "holiday": 22,
    "holiday_or": 22,
    "holiday_overtime": 10,
    "holiday_today": 1,
    "holiday_legal": 1,
    "holiday_recess": 1,
    "year_cn": "2021年",
    "month_cn": "2021年01月",
    "date_cn": "2021年01月01日",
    "yearweek_cn": "2020年第53周",
    "yearday_cn": "2021年第1天",
    "lunar_year_cn": "二零二零年",
    "lunar_month_cn": "二零二零年冬月",
    "lunar_date_cn": "二零二零年冬月十八",
    "lunar_yearday_cn": "2020年第343天",
    "week_cn": "星期五",
    "weekend_cn": "非周末",
    "workday_cn": "非工作日",
    "holiday_cn": "元旦",
    "holiday_or_cn": "元旦",
    "holiday_overtime_cn": "非节假日调休",
    "holiday_today_cn": "节日当天",
    "holiday_legal_cn": "法定节假日",
    "holiday_recess_cn": "假期节假日"
}

year 公历年份
month 公历月份
date 公历日期
yearweek 公历一年中的第几周，注意这里的年份是ISO-8601周编号年份，始终以周一至周日为一周。如需获取7天为一周直接使用年份中的天数除7即可。
yearday 公历一年中的第几天
lunar_year 农历年份
lunar_month 农历月份
lunar_date 农历日期
lunar_yearday 农历一年中的第几天
week 星期几
weekend 是否为周末
workday 是否为工作日（包含调休在内需要上班的日子）
holiday 节假日，这里使用两位数字枚举表示节假日，其中特殊数字10表示非节假日，特殊数字99表示全部节假日
holiday_or 其他节假日，枚举与节假日相同，表示同一天中的另一个节日，如 2020-10-01
holiday_overtime 节假日调休，枚举与节假日相同
holiday_today 是否为节日当天
holiday_legal 是否为法定节假日（三倍工资）
holiday_recess 是否为假期节假日（节日是否放假）