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

概述

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

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

快速开始

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

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 是否为假期节假日(节日是否放假)

节假日查询的功能到这里就介绍完了,大家在使用过程中遇到任何问题都可以 联系我

阅读 97

推荐阅读