万年历 / 农历 / 节气 / 节日
正常 NEW独立的日历工具接口。公历与农历互查、年月日干支、生肖、星座、二十四节气、传统节日与月历数据，全部本地计算，不依赖数据库、Redis 或第三方服务。
¥
0.002
/ 次
按次计费
健康检查
健康检查
调用方式：在接口地址后拼接
?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。
GET
http://www.shujuyu.cn/v1/api/wannianli/ping
JSON
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 您的API密钥，可在个人中心获取 |
返回参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0 表示成功 |
| msg | string | 提示信息，成功时为 pong |
| data | object | 业务数据对象 |
| data.name | string | 服务名称 |
| data.version | string | 服务版本号 |
| data.time | string | 服务器当前时间 |
| data.timezone | string | 服务使用的时区 |
| data.range | object | 支持的日期范围，含起止日期 |
| data.endpoints | array | 接口路径名列表 |
请求示例
返回示例
{"msg":"pong","code":0,"data":{"name":"万年历 API","time":"2026-11-01 13:31:07","range":{"end":"2100-12-31","start":"1900-01-31"},"version":"1.0.0","timezone":"Asia/Shanghai","endpoints":["ping","convert","today","month","solarterms","festivals"]}}
公历日期详情
一次返回指定公历日期的农历、干支、生肖、星座、节气、节日、下一个节气/节日
调用方式：在接口地址后拼接
?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。
GET
http://www.shujuyu.cn/v1/api/wannianli/convert
JSON
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 您的API密钥，可在个人中心获取 |
| date | string | 否 | 日期，支持 YYYY-MM-DD、YYYY/MM/DD、YYYYMMDD，默认当天 |
返回参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0 表示成功 |
| msg | string | 提示信息，成功时为 success |
| data | object | 业务数据对象 |
| data.solar | object | 公历日期信息对象 |
| data.lunar | object | 农历日期信息对象 |
| data.ganzhi | object | 年干支与日干支 |
| data.zodiac | string | 生肖名称 |
| data.constellation | string | 星座名称 |
| data.solar_term | string | 当天节气对象，非节气日为 null |
| data.festivals | array | 当天节日列表 |
| data.next_solar_term | object | 下一个节气及相差天数 |
| data.next_festival | object | 下一个节日及相差天数 |
请求示例
返回示例
{"msg":"success","code":0,"data":{"lunar":{"day":23,"text":"农历丙午年九月廿三","year":2026,"month":9,"zodiac":"马","day_name":"廿三","year_name":"丙午年","month_days":30,"month_name":"九月","short_text":"九月廿三","year_ganzhi":"丙午","is_leap_month":false},"solar":{"day":1,"date":"2026-11-01","year":2026,"month":11,"quarter":4,"weekday":7,"is_weekend":true,"weekday_en":"Sunday","day_of_year":305,"is_leap_year":false,"week_of_year":44,"weekday_name":"星期日","days_in_month":30,"weekday_short":"周日"},"ganzhi":{"day":"己卯","year":"丙午"},"zodiac":"马","festivals":[],"solar_term":null,"constellation":"天蝎座","next_festival":{"date":"2026-11-26","days":25,"name":"感恩节","type":"floating","lunar_text":"农历丙午年十月十八"},"next_solar_term":{"date":"2026-11-07","days":6,"name":"立冬","index":20}}}
今天的日期详情
等价于 convert 不传 date，按服务器 Asia/Shanghai 时区取当天
调用方式：在接口地址后拼接
?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。
GET
http://www.shujuyu.cn/v1/api/wannianli/today
JSON
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 您的API密钥，可在个人中心获取 |
返回参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0 表示成功 |
| msg | string | 提示信息，成功时为 success |
| data | object | 业务数据对象 |
| data.solar | object | 公历日期信息对象 |
| data.lunar | object | 农历日期信息对象 |
| data.ganzhi | object | 年干支与日干支 |
| data.zodiac | string | 生肖名称 |
| data.constellation | string | 星座名称 |
| data.solar_term | string | 当天节气对象，非节气日为 null |
| data.festivals | array | 当天节日列表 |
| data.next_solar_term | object | 下一个节气及相差天数 |
| data.next_festival | object | 下一个节日及相差天数 |
请求示例
返回示例
{"msg":"success","code":0,"data":{"lunar":{"day":25,"text":"农历丙午年九月廿五","year":2026,"month":9,"zodiac":"马","day_name":"廿五","year_name":"丙午年","month_days":30,"month_name":"九月","short_text":"九月廿五","year_ganzhi":"丙午","is_leap_month":false},"solar":{"day":3,"date":"2026-11-03","year":2026,"month":11,"quarter":4,"weekday":2,"is_weekend":false,"weekday_en":"Tuesday","day_of_year":307,"is_leap_year":false,"week_of_year":45,"weekday_name":"星期二","days_in_month":30,"weekday_short":"周二"},"ganzhi":{"day":"辛巳","year":"丙午"},"zodiac":"马","festivals":[],"solar_term":null,"constellation":"天蝎座","next_festival":{"date":"2026-11-26","days":23,"name":"感恩节","type":"floating","lunar_text":"农历丙午年十月十八"},"next_solar_term":{"date":"2026-11-07","days":4,"name":"立冬","index":20}}}
月历
返回指定公历月份的完整日历：每天的农历、节气、节日，以及按周排好的网格
调用方式：在接口地址后拼接
?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。
GET
http://www.shujuyu.cn/v1/api/wannianli/month
JSON
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 您的API密钥，可在个人中心获取 |
| year | int | 否 | 年份 1900-2100，默认当前年 |
| month | int | 否 | 月份 1-12，默认当前月 |
返回参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0 表示成功 |
| msg | string | 提示信息，成功时为 success |
| data | object | 业务数据对象 |
| data.year | int | 公历年份 |
| data.month | int | 公历月份，取值 1-12 |
| data.total_days | int | 当月总天数 |
| data.first_weekday | int | 当月 1 号的 ISO 星期，1 为周一 |
| data.weeks_count | int | 月历网格的周数 |
| data.days | array | 当月每日日期对象列表 |
| data.weeks | array | 按周一至周日排布的日历网格 |
| data.solar_terms | array | 当月节气列表 |
| data.festivals | array | 当月节日列表 |
请求示例
返回示例
{"msg":"success","code":0,"data":{"days":[{"day":1,"date":"2026-11-01","weekday":7,"is_today":false,"festivals":[],"lunar_day":23,"is_weekend":true,"lunar_text":"农历丙午年九月廿三","lunar_year":2026,"solar_term":null,"lunar_month":9,"lunar_short":"九月廿三","weekday_name":"星期日","is_leap_month":false,"weekday_short":"周日","lunar_day_name":"廿三","lunar_month_name":"九月"}],"year":2026,"month":11,"weeks":[[null,null,null,null,null,null,{"day":1,"date":"2026-11-01"}],[{"day":2,"date":"2026-11-02"}]],"festivals":[{"date":"2026-11-26","name":"感恩节","type":"floating"}],"total_days":30,"solar_terms":[{"date":"2026-11-07","name":"立冬","index":20},{"date":"2026-11-22","name":"小雪","index":21}],"weeks_count":6,"first_weekday":7}}
二十四节气
二十四节气
调用方式：在接口地址后拼接
?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。
GET
http://www.shujuyu.cn/v1/api/wannianli/solarterms
JSON
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 您的API密钥，可在个人中心获取 |
| year | int | 否 | 年份 1900-2100，默认当前年 |
返回参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0 表示成功 |
| msg | string | 提示信息，成功时为 success |
| data | object | 业务数据对象 |
| data.year | int | 节气所属公历年份 |
| data.total | int | 节气记录总数，通常为 24 |
| data.list | array | 二十四节气列表，含序号、名称与日期 |
请求示例
返回示例
{"msg":"success","code":0,"data":{"list":[{"date":"2026-01-05","name":"小寒","index":0},{"date":"2026-01-20","name":"大寒","index":1},{"date":"2026-02-04","name":"立春","index":2},{"date":"2026-02-18","name":"雨水","index":3},{"date":"2026-03-05","name":"惊蛰","index":4},{"date":"2026-03-20","name":"春分","index":5},{"date":"2026-04-05","name":"清明","index":6},{"date":"2026-04-20","name":"谷雨","index":7},{"date":"2026-05-05","name":"立夏","index":8},{"date":"2026-05-21","name":"小满","index":9},{"date":"2026-06-06","name":"芒种","index":10},{"date":"2026-06-21","name":"夏至","index":11},{"date":"2026-07-07","name":"小暑","index":12},{"date":"2026-07-23","name":"大暑","index":13},{"date":"2026-08-07","name":"立秋","index":14},{"date":"2026-08-23","name":"处暑","index":15},{"date":"2026-09-07","name":"白露","index":16},{"date":"2026-09-23","name":"秋分","index":17},{"date":"2026-10-08","name":"寒露","index":18},{"date":"2026-10-23","name":"霜降","index":19},{"date":"2026-11-07","name":"立冬","index":20},{"date":"2026-11-22","name":"小雪","index":21},{"date":"2026-12-07","name":"大雪","index":22},{"date":"2026-12-22","name":"冬至","index":23}],"year":2026,"total":24}}
节日列表
公历：元旦、情人节、妇女节、植树节、消费者权益日、愚人节、劳动节、青年节、护士节、儿童节、建党节、建军节、教师节、国庆节、万圣节、平安夜、圣诞节
调用方式：在接口地址后拼接
?key=您的API密钥 即可直接调用；也可改用 Authorization: Bearer 或 X-App-Key 请求头传递，避免密钥出现在访问日志中。
GET
http://www.shujuyu.cn/v1/api/wannianli/festivals
JSON
请求参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| key | string | 是 | 您的API密钥，可在个人中心获取 |
| year | int | 否 | 公历年份 1900-2100，默认当前年 |
返回参数说明
| 参数名 | 类型 | 说明 |
|---|---|---|
| code | int | 业务状态码，0 表示成功 |
| msg | string | 提示信息，成功时为 success |
| data | object | 业务数据对象 |
| data.year | int | 节日所属公历年份 |
| data.total | int | 节日记录总数 |
| data.list | array | 节日列表，含日期、名称与类型 |
请求示例
返回示例
{"msg":"success","code":0,"data":{"list":[{"date":"2026-01-01","name":"元旦","type":"solar","weekday":4,"is_weekend":false,"lunar_text":"农历乙巳年冬月十三","weekday_name":"星期四"},{"date":"2026-02-16","name":"除夕","type":"lunar","weekday":1,"is_weekend":false,"lunar_text":"农历乙巳年腊月廿九","weekday_name":"星期一"},{"date":"2026-02-17","name":"春节","type":"lunar","weekday":2,"is_weekend":false,"lunar_text":"农历丙午年正月初一","weekday_name":"星期二"},{"date":"2026-04-05","name":"清明节","type":"solar_term","weekday":7,"is_weekend":true,"lunar_text":"农历丙午年二月十八","weekday_name":"星期日"},{"date":"2026-09-25","name":"中秋节","type":"lunar","weekday":5,"is_weekend":false,"lunar_text":"农历丙午年八月十五","weekday_name":"星期五"}],"year":2026,"total":32}}
产品说明
产品概述
独立的日历工具接口。公历与农历互查、年月日干支、生肖、星座、二十四节气、传统节日与月历数据，全部本地计算，不依赖数据库、Redis 或第三方服务。
使用场景
数据查询：快速集成 万年历 / 农历 / 节气 / 节日 到您的应用中
业务系统：将 万年历 / 农历 / 节气 / 节日 数据嵌入业务流程
开发工具：通过 API 接口获取 生活服务 数据
数据分析：基于 万年历 / 农历 / 节气 / 节日 数据进行分析和决策
费用计算
按次计费单价
¥0.002
/ 次
每次调用接口从账户余额中扣除相应费用，VIP 用户可享折扣
扣费优先级
免费额度
次数包
余额扣费
计费方式详解
1
免费额度
· 接口每日免费额度已关闭
· VIP 用户月度免费额度：
· 个人版：每月 5000 次，本接口月上限 5000 次
· 专业版：每月 30000 次，本接口月上限 30000 次
· 企业版：每月 200000 次，本接口月上限 200000 次
· 账户如有注册/活动赠送的免费次数，会优先于接口免费额度扣减
· VIP 月度免费额度仅适用于单次售价不高于 ¥0.0800/次 的接口；接口每日免费额度按接口配置执行
VIP 月度免费额度每月重置，未使用部分不累计至下月。
· VIP 用户月度免费额度：
· 个人版：每月 5000 次，本接口月上限 5000 次
· 专业版：每月 30000 次，本接口月上限 30000 次
· 企业版：每月 200000 次，本接口月上限 200000 次
· 账户如有注册/活动赠送的免费次数，会优先于接口免费额度扣减
· VIP 月度免费额度仅适用于单次售价不高于 ¥0.0800/次 的接口；接口每日免费额度按接口配置执行
VIP 月度免费额度每月重置，未使用部分不累计至下月。
2
次数包
预付费购买固定调用次数，折算单价与按次付费相同，用完为止。
次数包为独立计费，不与 VIP 折扣叠加。
请在有效期内使用，过期后未使用的次数不可再用。
次数包为独立计费，不与 VIP 折扣叠加。
请在有效期内使用，过期后未使用的次数不可再用。
3
余额扣费
按次从账户余额扣除费用；所有用户可享量折扣，VIP 用户额外享 VIP 折扣。
扣费公式：实际扣费 = 接口单价 × (1 - VIP 折扣比例 - 量折扣比例)，并受总折扣上限和最低利润率保护约束
VIP 折扣： 个人版9折 专业版8折 企业版7折
量折扣： 月付费调用 ≥1000 次享 2%、 月付费调用 ≥10000 次享 5%、 月付费调用 ≥20000 次享 10%
· 量折扣按账号当月全部接口的付费调用次数统计，达到更高档位时按更高档位计算
总折扣上限：VIP 折扣 + 量折扣合计不超过 50%
最低利润率保护：折后价不得低于成本价 × (1 + 15%)；若接口售价本身低于该保护价，则取消折扣并按售价计费
余额不足时调用将失败，请及时充值。
扣费公式：实际扣费 = 接口单价 × (1 - VIP 折扣比例 - 量折扣比例)，并受总折扣上限和最低利润率保护约束
VIP 折扣： 个人版9折 专业版8折 企业版7折
量折扣： 月付费调用 ≥1000 次享 2%、 月付费调用 ≥10000 次享 5%、 月付费调用 ≥20000 次享 10%
· 量折扣按账号当月全部接口的付费调用次数统计，达到更高档位时按更高档位计算
总折扣上限：VIP 折扣 + 量折扣合计不超过 50%
最低利润率保护：折后价不得低于成本价 × (1 + 15%)；若接口售价本身低于该保护价，则取消折扣并按售价计费
余额不足时调用将失败，请及时充值。
VIP 权益对比
| 等级 | 每月免费次数 | 本接口月免费上限 | 折扣 | VIP 折后单价 |
|---|---|---|---|---|
| 免费版 | 按接口配置 | — | - | ¥0.002/次 |
| 个人版 | 5000 次 | 5000 次 | 10% | ¥0.0018/次 |
| 专业版 | 30000 次 | 30000 次 | 20% | ¥0.0016/次 |
| 企业版推荐 | 200000 次 | 200000 次 | 30% | ¥0.0014/次 |
* VIP 月度免费额度每月重置。每月免费次数为账号级 VIP 月额度，本接口月免费上限为其中对本接口的限制（接口可单独设置上限或关闭）。VIP 折扣仅适用于余额扣费方式，VIP 折后单价不含量折扣。
本接口已关闭接口级月度免费额度（不影响 VIP 月度免费额度）。接口每日免费额度已关闭。
费用计算示例
* 以下示例未包含量折扣，量折扣按账号当月全部接口的付费调用量另行计算。
示例1：普通用户按次付费
调用 1000 次，费用 = 0.002 × 1000 = ¥2.00
示例2：个人版用户按次付费（仅 VIP 折扣，已考虑最低利润率保护）
调用 1000 次，折扣约 10%，费用 = 0.002 × (1 - 10%) × 1000 ≈ ¥1.80
错误码说明
本接口未定义专属错误码，调用时请参考通用错误码体系。
查看通用错误码参考
| 错误码 | 说明 | 解决方案 |
|---|---|---|
| 200 | 请求成功 | - |
| 400000 | 请求参数错误 | 检查参数名、格式与取值 |
| 401000 | 认证失败 | 检查 Authorization: Bearer 密钥是否正确、是否过期 |
| 401002 | 缺少 API 认证参数 | 请求未携带 key，请通过 URL 参数 key 或请求头 Authorization 传递密钥 |
| 402000 | 账户余额不足 | 充值后重试 |
| 403000 | 无访问权限 | 确认密钥权限、接口范围与 IP 白名单是否满足要求 |
| 404001 | 接口或端点不存在 | 检查 API 与端点的请求路径 |
| 409000 | 请求冲突 | 请稍后重试 |
| 422000 | 参数校验失败 | 检查参数格式与取值 |
| 429001 | 请求频率超限（QPS） | 降低请求频率，或升级套餐提升额度 |
| 429002 | 分钟级调用频率超限 | 降低调用频率，或升级套餐提升额度 |
| 429003 | 小时级调用额度已用完 | 升级套餐提升额度，或整点后重试 |
| 429004 | 今日调用额度已用完 | 升级套餐提升额度，或次日重试 |
| 500000 | 服务器内部错误 | 携带响应中的 request_id 联系技术支持 |
| 502000 | 服务暂时不可用 | 稍后重试 |
| 503000 | 服务暂时不可用 | 稍后重试 |
| 504000 | 请求超时 | 稍后重试 |
更新日志
暂无更新日志