农历节气生肖转换

接口标识: lunar 价格: 0.005 元/次同步响应

接口介绍
接口文档
在线测试

接口简介

农历节气生肖转换接口支持公历与农历双向互转：传公历日期查对应农历，传农历日期（闰月可指定）反查公历，两者都传以公历为准。一次返回农历年月日数字与中文写法、是否闰月、生肖、年月日三柱干支、当日节气与传统节日名称，除夕按次日是否为正月初一判定，无节气或节日时返回空字符串。公历年份支持 1900~9999 年。适合日历工具、农历生日提醒与民俗文化应用场景。

详细介绍

![农历节气生肖转换接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261111/apiops_lunar__1794363303_a58a374d7c72.png)

公历生日对应的农历是哪天、属什么、干支是什么？传入日期一次转换，还告诉你当日节气与传统节日。

## 接口概述
面向日历工具、民俗生活服务与传统文化类应用需要农历信息的场景，接口支持公历与农历双向转换：传公历日期查对应农历，传农历日期（可指定闰月）反查公历。一次调用同时输出农历年月日数字与中文写法、生肖、年月日三柱干支、当日节气与传统节日名称，同步返回、字段规范命名，可直接嵌入日历展示、农历生日提醒、民俗日历等业务功能，免去自建天文历算法与节日判定逻辑。

## 核心能力
1. **双向转换**：公历转农历、农历转公历都支持，闰月可明确指定，两参同传以公历为准。
2. **中文写法**：输出「2026年正月初一」「闰二月初一」等规范中文农历表述，界面可直接展示。
3. **生肖与干支**：同时返回生肖与年柱、月柱、日柱三组干支。
4. **节气节日识别**：当日节气与春节、中秋、除夕等传统节日自动识别，除夕按次日是否为正月初一判定，无则返回空串。

## 产品优势
1. **信息丰富**：一次调用拿到日期互转、生肖、干支、节气、节日五类信息。
2. **天文口径**：基于天文历算法实时推算，而非简单查表，闰月与节气判定准确。
3. **接入简单**：POST 同步返回，字段规范命名，即接即用。
4. **范围宽广**：公历年份支持 1900 至 9999 年，历史与远期日期都能转。
5. **降本增效**：日历类应用无需自研维护农历算法与节日表。

## 效果展示
一句话理解：它就像一位双历翻译官——你说公历，它报出农历日子、生肖和干支；你说农历，它也能翻回公历。

以一次真实调用为例，你要传的参数：

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| date | 2026-02-17 | 公历日期 YYYY-MM-DD，与 lunar_date 二选一，都传以 date 优先 |

你会拿到的结果：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 公历日期 | `"2026-02-17"` | `solar_date` |
| 农历年月日 | 2026 / 1 / 1 | `lunar_year` / `lunar_month` / `lunar_day`，数字形式 |
| 农历中文 | `"2026年正月初一"` | `lunar_date` |
| 是否闰月 | false | `is_leap_month` |
| 生肖 | `"马"` | `zodiac` |
| 三柱干支 | 丙午年 庚寅月 壬戌日 | `ganzhi_year` / `ganzhi_month` / `ganzhi_day` |
| 节气与节日 | 节气无，节日为春节 | `jieqi` / `festival`，无则空字符串 |

API请求示例：

```
POST /api/lunar
date=2026-02-17
```

API响应示例：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "solar_date": "2026-02-17",
    "lunar_year": 2026,
    "lunar_month": 1,
    "lunar_day": 1,
    "is_leap_month": false,
    "lunar_date": "2026年正月初一",
    "zodiac": "马",
    "ganzhi_year": "丙午",
    "ganzhi_month": "庚寅",
    "ganzhi_day": "壬戌",
    "jieqi": "",
    "festival": "春节"
  },
  "request_id": "a2c4e6f8b0d143579e1a3c5e7f9b0d2a"
}
```

lunar_date 为农历中文写法，jieqi 与 festival 当日无对应时为空字符串；改传 lunar_date（如 2026-01-01）即可由农历反查公历。

## 应用场景
- **日历工具**：日历页展示每日农历、节气与节日信息。
- **生日提醒**：把用户的农历生日换算成当年公历日期，按时提醒。
- **民俗服务**：传统文化、民俗日历类应用展示生肖与干支信息。
- **日期属性标注**：为候选日期批量标注农历与节日属性，供用户参考。

## 应用案例
**日历应用开发者**：产品要在日历页展示农历、节气与节日，自研维护天文历算法和节日判定成本太高。接入本接口后，每个日期一次查询即得农历中文、生肖、干支与节日字段，直接渲染上屏，两周完成原本排期一个季度的功能。

**生日提醒服务运营**：很多用户只记得农历生日，而每年对应的公历日期都不同。用本接口把农历生日换算成当年公历日期来设定提醒，闰月出生的用户也能通过 is_leap 正确处理。

常见问题

Q：闰月怎么查？

A：农历转公历时传 lunar_date 并将 is_leap 置为 true 表示闰月；返回结果中 is_leap_month 标明该日是否处于闰月。

Q：date 和 lunar_date 都传了按哪个算？

A：以 date（公历）优先；两者都不传会返回参数错误提示。

Q：支持哪些日期范围？

A：公历年份支持 1900~9999 年；农历日期不存在时（如该月没有三十）返回参数错误。节日与节气按传统口径识别，无则返回空字符串。

农历生肖干支节气日历

接口地址： https://www.phpwc.cn/api/lunar

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`date`	string	选填	-	公历日期 YYYY-MM-DD（与 lunar_date 二选一，date 优先）
`lunar_date`	string	选填	-	农历日期 YYYY-MM-DD（年=农历年，月=1-12，日=1-30）
`is_leap`	boolean	选填	`false`	lunar_date 的月是否为闰月

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`solar_date`	string	公历日期
`lunar_year`	int	农历年
`lunar_month`	int	农历月
`lunar_day`	int	农历日
`is_leap_month`	boolean	是否闰月
`lunar_date`	string	农历中文（如二〇二六年九月初一）
`zodiac`	string	生肖
`ganzhi_year`	string	年干支
`ganzhi_month`	string	月干支
`ganzhi_day`	string	日干支
`jieqi`	string	当日节气（无则空）
`festival`	string	传统节日（无则空）
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

请先登录后使用在线测试