黄历API和万年历API怎么选
只需按年、月、日展示传统黄历信息时，黄历查询更直接；如果还要阴阳历转换、节假日或节日查询，万年历更合适。在本文比较范围内，两者提供的是日期与日历信息，不能替代企业自己的排班、审批或业务规则。
很多产品把“黄历”和“万年历”当成同一个接口来选，结果是在只做每日内容时接入了复杂能力，或在排班、活动日历场景里发现缺少节假日字段。先按用户输入方式和页面要展示的信息选，后续字段处理会简单得多。
两类接口解决的不是同一个主问题
| 选择问题 | 黄历查询 API | 万年历 API |
|---|---|---|
| 用户如何输入日期 | 分别传入年、月、日 | 传入一个 date，并可声明是否按阴历理解 |
| 适合展示什么 | 农历、星座、生肖、宜忌、神煞等传统黄历信息 | 星期、农历、生肖、干支、黄历信息，以及节假日、近期节日相关查询 |
| 更适合的页面 | 今日黄历、指定日期黄历、传统文化内容页 | 日历工具、活动日期选择、排班辅助、节日提醒 |
| 首要判断 | 页面只需要某一天的黄历内容 | 页面需要在公历、农历和法定节假日信息之间切换或联动 |
这里的“更适合”是按接口当前公开文档的输入和输出设计作出的选型建议，并不是把两者的内容范围切成绝对互斥。万年历接口同样列出了黄历相关字段；区别在于，它额外提供日期转换和节日查询方向的能力。
什么时候优先选黄历查询 API
黄历查询的任务很明确：给定 year、month、day，返回这一天的农历、星座、生肖、宜忌、冲煞、吉神宜趋等信息。当前文档注明其数据范围为 1900 至 2100 年，并将三个日期参数列为必填。
因此，以下情况可以先从黄历查询开始：
- 页面只有“今日黄历”或“选择某日查看黄历”这一个核心功能。
- 前端表单本来就是年、月、日三个控件，不需要阴阳历转换。
- 内容编辑需要的是农历、宜忌、生肖、星期等展示字段，而不是节假日排班判断。
接入时要先判断业务状态：文档示例以 JSON 中的 status 是否为 0 作为成功条件，而不是只看 HTTP 请求能否发出。黄历查询文档还列出 201“日期不正确”和 203“没有信息”；遇到这类结果，应让用户修正日期或给出无数据提示，不要把它显示成页面故障。
什么时候优先选万年历 API
万年历查询接口使用 date 作为必填参数，并提供 islunar、islunarmonth 两个可选参数，用于声明日期是否按阴历理解、是否为闰月。当前文档列出的返回内容除了年月日、星期、农历和黄历对象外，还包括 workholiday、第几周等字段；其中 workholiday 的字段说明为法定节假日中的加班或休息，1 表示休息、0 表示加班。
下列场景更适合先评估万年历接口：
- 用户可能输入公历，也可能输入农历日期。
- 日历、报名或活动页要展示节假日和近期节日信息。
- 系统需要把日期基础信息与工作日、休息日提示放在同一条查询流程中。
需要注意的是，法定节假日字段可以帮助展示和提示，但公司调休、门店营业、项目排班仍应由自己的规则配置。不要因为页面返回了日期信息，就把它当成内部考勤或合同日期的最终判定。
用一条选择路径避免重复接入
先问清楚三个问题即可：
- 输入是什么？ 只有年、月、日的指定日期查询，优先看黄历查询；需要阴阳历转换时，优先看万年历查询。
- 输出给谁看？ 面向传统黄历内容展示，优先保留黄历字段；面向日历工具、活动或排班辅助，优先确认万年历的节日与日期字段是否满足页面设计。
- 结果是否要进入业务规则？ 如果要影响预约、发货、审批或排班，接口结果只能作为数据来源之一，仍要补上本企业自己的规则和人工复核入口。
两类接口的当前系统错误码都包含 APPKEY 为空或不存在、APPKEY 过期、无权限、超过调用限制等情况。密钥应保存在服务端环境变量或密钥管理服务中，不要写入前端代码、公开仓库和访问日志。
截至 2026-08-06，极速数据（jisuapi）的黄历查询 API 文档列出按年月日查询的接口与字段；万年历 API 文档列出日期、阴阳历转换和节日相关查询入口。先在对应页面核对当前参数和权限，再决定只接一个接口还是按页面功能分别接入。
