杂项

查询节假日与万年历

0次调用
1 积分/次

查询指定日期、月份或年份的万年历与节假日信息。

GET
uapis.cn
/api/v1/misc/holiday-calendar
查询参数
8
date
string

按天查询时填写这个参数,例如查某一天。格式:YYYY-MM-DD。和 monthyear 三选一。

month
string

按月查询时填写这个参数,例如查某个月。格式:YYYY-MM。和 dateyear 三选一。

year
string

按年查询时填写这个参数,例如查某一年。格式:YYYY。和 datemonth 三选一。

timezone
string

时区名称,默认 Asia/Shanghai。

holiday_type
string

节日筛选类型,默认 all。

include_nearby
boolean

是否返回前后最近节日,仅 date 模式生效,默认 false。month/year 模式会忽略此参数。

nearby_limit
integer

返回最近节日数量限制,默认 7,最大 30。仅 date 模式 + include_nearby=true 生效。

exclude_past
boolean

传 true 时,会过滤今天之前已经过去的节日。默认 false。

功能概述

这个接口支持三种查询方式:按天(date)、按月(month)和按年(year)。调用时三者选一个传入即可。

如果你只关心某一类事件,可以通过 holiday_type 进行筛选,例如只看法定休假/调休、公历节日、农历节日或节气。

date 模式下,传 include_nearby=true 可以额外返回该日期前后最近的节日;返回数量由 nearby_limit 控制,默认 7,最大 30。

如果你只想保留今天和之后的节日,可以再传 exclude_past=true 过滤已经过去的节日。

查询参数

date
string可选

按天查询时填写这个参数,例如查某一天。格式:YYYY-MM-DD。和 monthyear 三选一。

month
string可选

按月查询时填写这个参数,例如查某个月。格式:YYYY-MM。和 dateyear 三选一。

year
string可选

按年查询时填写这个参数,例如查某一年。格式:YYYY。和 datemonth 三选一。

timezone
string可选

时区名称,默认 Asia/Shanghai。

holiday_type
string可选

节日筛选类型,默认 all。

include_nearby
boolean可选

是否返回前后最近节日,仅 date 模式生效,默认 false。month/year 模式会忽略此参数。

nearby_limit
integer可选

返回最近节日数量限制,默认 7,最大 30。仅 date 模式 + include_nearby=true 生效。

exclude_past
boolean可选

传 true 时,会过滤今天之前已经过去的节日。默认 false。

响应

200 / 请求成功

查询成功,返回指定范围的万年历与节假日信息。

JSON
{
  // 查询模式:day、month、year。
  "mode": "day",
  // 请求参数回显。
  "query": {
    // 日视图查询参数。date 模式下为 YYYY-MM-DD,其余模式下为空字符串。
    "date": "2025-10-01",
    // 节日筛选类型。
    "holiday_type": "legal",
    // 是否开启前后最近节日查询。
    "include_nearby": true,
    // 是否过滤今天之前已经过去的节日。
    "exclude_past": true,
    // 月视图查询参数。month 模式下为 YYYY-MM,其余模式下为空字符串。
    "month": "",
    // 前后最近节日返回数量上限。
    "nearby_limit": 7,
    // 实际生效的时区。
    "timezone": "Asia/Shanghai",
    // 年视图查询参数。year 模式下为 YYYY,其余模式下为空字符串。
    "year": ""
  },
  // 统计摘要。
  "summary": {
    // 查询范围内总天数。
    "total_days": 1,
    // 查询范围内周末天数。
    "weekend_days": 0,
    // 查询范围内工作日天数(含法定调休上班)。
    "workdays": 0,
    // 查询范围内休息日天数(含周末和法定休假)。
    "rest_days": 1,
    // 按 holiday_type 过滤后的节日事件总数。
    "holiday_events": 1,
    // 法定休假日天数。
    "legal_rest_days": 1,
    // 法定调休上班天数。
    "legal_workdays": 0
  },
  // 日期明细列表。
  "days": [
    {
      // 公历日期(YYYY-MM-DD)。
      "date": "2025-10-01",
      // 公历年份。
      "year": 2025,
      // 公历月份。
      "month": 10,
      // 公历日期(天)。
      "day": 1,
      // 中文星期,如星期三。
      "weekday_cn": "星期三",
      // 是否为周末。
      "is_weekend": false,
      // 是否为工作日(含法定调休上班日)。
      "is_workday": false,
      // 是否为休息日。
      "is_rest_day": true,
      // 当天是否存在节日、节气或法定事件。
      "is_holiday": true,
      // 法定节假日名称,无则为空或不返回。
      "legal_holiday_name": "国庆中秋",
      // 法定假日类型:rest 或 workday_adjust。
      "legal_holiday_type": "rest",
      // 公历节日名称。有值时返回。
      "solar_festival": "国庆节",
      // 农历节日名称。有值时返回。
      "lunar_festival": "",
      // 节气名称。有值时返回。
      "solar_term": "",
      // 农历年份(数字)。
      "lunar_year": 2025,
      // 农历月份(数字)。
      "lunar_month": 8,
      // 农历日期(数字)。
      "lunar_day": 10,
      // 农历月份中文名称。
      "lunar_month_name": "八月",
      // 农历日期中文名称。
      "lunar_day_name": "初十",
      // 干支年。
      "ganzhi_year": "乙巳",
      // 干支月。
      "ganzhi_month": "乙酉",
      // 干支日。
      "ganzhi_day": "癸卯"
    }
  ],
  // 节日事件列表。
  "holidays": [
    {
      // 事件日期(YYYY-MM-DD)。
      "date": "2025-10-01",
      // 事件名称。
      "name": "国庆中秋",
      // 事件类型。
      "type": "legal_rest",
      // 仅 legal_workday_adjust 场景才会返回。
      "is_workday": true
    }
  ],
  // 前后最近节日,仅 include_nearby=true 且 date 模式返回。
  "nearby": {
    // 当前查询日期之前最近的节日列表(按时间倒序)。
    "previous": [
      {
        // 聚合日期。
        "date": "2025-09-28",
        // 该日期上的节日事件列表。
        "events": [
          {
            // 事件日期。
            "date": "2025-09-28",
            // 事件名称。
            "name": "国庆中秋",
            // 事件类型。
            "type": "legal_workday_adjust",
            // 仅调休上班事件返回。
            "is_workday": true
          }
        ]
      }
    ],
    // 当前查询日期之后最近的节日列表(按时间正序)。
    "next": [
      {
        // 聚合日期。
        "date": "2025-10-02",
        // 该日期上的节日事件列表。
        "events": [
          {
            // 事件日期。
            "date": "2025-10-02",
            // 事件名称。
            "name": "国庆中秋",
            // 事件类型。
            "type": "legal_rest",
            // 仅调休上班事件返回。
            "is_workday": true
          }
        ]
      }
    ]
  }
}

400 / 错误的请求

请求参数错误。常见原因:

  • datemonthyear 未传或同时传入多个
  • 日期格式错误:date 必须为 YYYY-MM-DDmonth 必须为 YYYY-MMyear 必须为 YYYY
  • holiday_type 非法
  • timezone 非法
JSON
{
  // 业务状态码,400 表示请求参数错误。
  "code": 400,
  // 具体错误原因提示。
  "message": "date/month/year 只能传一个"
}