← API.MAO.MS Home简体 · 繁體

Lunar Calendar Conversion

Bidirectional Gregorian ↔ Chinese lunar conversion with sexagenary (Ganzhi) year/month/day, zodiac and weekday. Local calendar tables for 1900–2100, matching the official Chinese calendar — no third-party calls.

Endpoint

Method & pathDescription
GET /v1/lunarWith no parameters, returns today (Beijing time). Pass date for Gregorian → lunar, or lunar for lunar → Gregorian
ParameterValuesDescription
dateYYYY-MM-DDGregorian date, for Gregorian → lunar; defaults to today
lunarYYYY-MM-DDLunar date (year-month-day), for lunar → Gregorian; takes precedence over date
leap1With lunar: pass 1 when the lunar month is a leap month
langzh / en / hant / tw / hkLanguage of error messages; Traditional variants also convert the lunar name fields

Example response

GET /v1/lunar?date=2024-02-10

{"code":0,"message":"ok","data":{"solar":"2024-02-10","weekday":6,"weekday_cn":"星期六","lunar":{"year":2024,"month":1,"day":1,"is_leap":false,"month_name":"正月","day_name":"初一","date_cn":"甲辰年正月初一","year_ganzhi":"甲辰","month_ganzhi":"丙寅","day_ganzhi":"甲辰","zodiac":"龙","zodiac_en":"Dragon"}}}
FieldDescription
solarGregorian date (the converted result for lunar → Gregorian)
weekday / weekday_cnWeekday: 0 = Sunday, 1–6 = Monday–Saturday; weekday_cn is the Chinese name
lunar.year / month / dayLunar year, month and day (numbers)
lunar.is_leapWhether the day falls in a leap month
lunar.month_name / day_name / date_cnLunar month name, day name and the full lunar date string (Chinese)
lunar.year_ganzhi / month_ganzhi / day_ganzhiSexagenary year, month and day. The year pillar turns at Spring Festival; the month pillar follows the lunar month (Wǔhǔdùn), a leap month sharing its base month
lunar.zodiac / zodiac_enZodiac animal (by lunar year) and its English name

Supported range: Gregorian 1900-01-31 to 2100-12-31 (lunar years 1900–2100). A lunar date that does not exist (no such leap month that year, or day 30 in a 29-day month) returns 400 with the reason.

Call statistics

This endpoint group has been called 18 times in total · 0 today · All endpoints

EndpointPathTodayTotal
Lunar conversion/v1/lunar018

Try it

Gregorian → lunar:

Lunar → Gregorian:

Use the buttons above (the prefilled lunar example is the 1st day of the leap 2nd month, 2023)