农历日期转换 API

简单易用的公历农历转换服务，支持节日查询、生肖、天干地支等功能

🔍 在线测试

// 结果将显示在这里

📖 API 使用说明

接口地址

GET /api/lunar

请求参数说明

参数名 说明 是否必填 示例
date

日期字符串，格式根据转换类型不同而不同：

  • 公历转农历：YYYY-MM-DD
  • 农历转公历：YYYY-MM-DD-0（最后的0表示是否闰月：0非闰月，1闰月）
  • 特殊值：today（表示今天的日期）
 是 2024-03-20
2024-01-01-0
today
type

转换类型：

  • solar2lunar：公历转农历
  • lunar2solar：农历转公历
 否 默认：solar2lunar
timezone

时区设置（仅在 date=today 时有效）：

  • 数字，表示 UTC 时区偏移小时数
  • 范围：-12 到 +14
  • 例如：8 表示北京时间 (UTC+8)
  • 例如：-5 表示纽约时间 (UTC-5)
  • 例如：0 表示格林威治时间 (UTC)
 否 默认：8 (北京时间)

调用示例

1. 获取今天的农历（指定时区）

支持的时区示例：

返回数据：

{
    "code": 200,
    "data": {
        "lunarYear": 2024,        // 农历年
        "lunarMonth": 2,          // 农历月
        "lunarDay": 10,           // 农历日
        "lunarMonthName": "二月",  // 农历月份（如：正月、二月、闰二月）
        "lunarDayName": "初十",    // 农历日期（如：初一、十五、廿九）
        "zodiac": "龙",           // 生肖
        "yearInGanZhi": "甲辰",    // 年份天干地支
        "monthInGanZhi": "庚寅",   // 月份天干地支
        "dayInGanZhi": "丙寅",     // 日期天干地支
        "festival": ["春分"],      // 节日（包括农历节日和公历节日）
        "isLeap": false,          // 是否闰月
        "weekDay": "星期三",       // 星期几
        "solar": {                // 公历日期信息
            "year": 2024,
            "month": 3,
            "day": 20,
            "date": "2024-03-20"
        }
    }
}

2. 公历转农历

返回数据：

{
    "code": 200,
    "data": {
        "lunarYear": 2024,        // 农历年
        "lunarMonth": 2,          // 农历月
        "lunarDay": 10,           // 农历日
        "lunarMonthName": "二月",  // 农历月份（如：正月、二月、闰二月）
        "lunarDayName": "初十",    // 农历日期（如：初一、十五、廿九）
        "zodiac": "龙",           // 生肖
        "yearInGanZhi": "甲辰",    // 年份天干地支
        "monthInGanZhi": "庚寅",   // 月份天干地支
        "dayInGanZhi": "丙寅",     // 日期天干地支
        "festival": ["春分"],      // 节日（包括农历节日和公历节日）
        "isLeap": false,          // 是否闰月
        "weekDay": "星期三",       // 星期几
        "solar": {                // 公历日期信息
            "year": 2024,
            "month": 3,
            "day": 20,
            "date": "2024-03-20"
        }
    }
}

3. 农历转公历

返回数据：

{
    "code": 200,
    "data": {
        "solarYear": 2024,        // 公历年
        "solarMonth": 3,          // 公历月
        "solarDay": 20,           // 公历日
        "solarFestival": [],      // 公历节日
        "weekDay": "星期三",       // 星期几
        "date": "2024-03-20"      // 格式化的日期字符串
    }
}

错误响应

当发生错误时，API 会返回以下格式的数据：

{
    "code": 400,      // 错误码：400表示请求参数错误，500表示服务器错误
    "error": "错误信息" // 具体的错误说明
}

使用限制

常见使用场景

1. 获取今日农历

如果你想在你的网站或应用中显示今天的农历日期，可以使用以下代码：

JavaScript 示例代码： 
// 获取今天的农历日期
async function getTodayLunar() {
    try {
        // 调用API
        const response = await fetch(`https://lunarapi.vercel.app/api/lunar?date=today`);
        const data = await response.json();
        
        if (data.code === 200) {
            // 示例显���农历日期
            console.log(
                `今天是农历 ${data.data.lunarYear}年`
                + `${data.data.lunarMonthName}`
                + `${data.data.lunarDayName}`
                + `，${data.data.zodiac}年`
                + `，${data.data.weekDay}`
            );
            
            // 如果有节日则显示
            if (data.data.festival.length > 0) {
                console.log(`今天是: ${data.data.festival.join('、')}`);
            }
        }
    } catch (error) {
        console.error('获取农历日期失败:', error);
    }
}

// 立即执行一次
getTodayLunar();

// 如果需要每天自动更新，可以这样写：
// 设置在每天凌晨 00:00:01 更新
function scheduleNextUpdate() {
    const now = new Date();
    const tomorrow = new Date(now);
    tomorrow.setDate(tomorrow.getDate() + 1);
    tomorrow.setHours(0, 0, 1, 0);
    
    const timeUntilNextUpdate = tomorrow - now;
    setTimeout(() => {
        getTodayLunar();
        scheduleNextUpdate(); // 设置下一次更新
    }, timeUntilNextUpdate);
}

// 启动定时更新
scheduleNextUpdate();

运行效果示例：

// 结果将显示在这里