用途
calendar-api 是一个中文黄历查询工具,用于获取任意日期的综合传统历法信息。它通过调用接口盒子 API(API ID: 278)返回数据,适合需要查询农历、干支、宜忌、节气等传统历法内容的场景。
主要能力
脚本将返回的数据整理为以下类别:
- 📆 公历:年、月、日、星期、闰年
- 🌙 农历:农历年、月、日
- 🎊 节日:公历节日、农历节日
- ⭐ 星座与生肖:星座、生肖、每日生肖
- 📜 干支:年/月/日干支、日纳音
- 🌿 节气与物候:节气、描述、物候、数九、三伏
- ☯ 宜忌:宜、忌、吉神凶神
- 🧭 方位:喜、财、福、贵神方位
- ⚠️ 冲煞:相冲、日冲、天神、黄道黑道
- 🔢 值星与神煞:值星(十二值星)、十二神、六曜、月相
- 🌟 星宿:二十八星宿、动物、吉凶、七曜、四宫、四象
- 📖 彭祖与胎神:彭祖百忌、胎神方位、太岁
- 📅 佛道历:佛历、道历、伊斯兰历
- 📊 其他:五行、儒略日、九星、季节
使用方式
脚本路径:scripts/getzdday.py
查询今天:
python scripts/getzdday.py
查询指定日期:
python scripts/getzdday.py 2025-06-05
输出原始 JSON(调试):
python scripts/getzdday.py 2025-06-05 --json
环境变量:
- JKHZ_ID:接口盒子(apihz.cn)用户 ID
- JKHZ_KEY:接口盒子 API key
脚本会自动从 scripts/.env 加载这些变量,模板见 scripts/.env.example。
依赖安装:
pip install python-dotenv tzdata
执行规则:直接运行用户请求的命令,无需预先检查依赖、环境变量或配置。若出现问题,脚本会以清晰的错误信息失败,届时再检查并修复。
适用场景
- 查询某一天的公历、农历、干支、节气等传统历法信息
- 查看宜忌、方位、冲煞、星宿等黄历内容
- 需要以格式化文本直接展示,或通过 --json 获取原始数据用于进一步处理
限制
- 默认使用今天日期(Asia/Shanghai 时区)
- API 年份范围为 1800 年至下一年
- API 可能因日期不同返回不同字段,脚本会动态显示所有非空字段
- 输出语言需与用户提问语言一致:用户用中文提问则所有类别标签与描述用中文,用英文提问则用英文
- 需自行配置接口盒子的用户 ID 与 API key