1. Terms

The Chinese lunar calendar is a lunisolar calendar which identifies years, months, and days according to astronomical phenomena. A common year has 12 months and a leap year has 13 months, and an ordinary year has 353–355 days while a leap year has 383–385 days.

The Gregorian calendar, i.e. western calendar, is the calendar used in most parts of the world. The average calendar year is 365.2425 days long, closely approximating the 365.2422-day ‘tropical’ or ‘solar’ year that is determined by the Earth’s revolution around the Sun. The Gregorian calendar has 12 months of 28–31 days each. The year consists of 365 days, with a leap day being added to February in the leap years.

The Chinese Zodiac(or sheng xiao) features the names of animals in a zodiac cycle consisting of 12 animals: rat, ox, tiger, rabbit, dragon, snake, horse, sheep, monkey, rooster, dog, and pig.

A solar term (or jie qi) is any of twenty-four periods in Chinese calendars that matches a particular astronomical event or signifies some natural phenomenon.

The sexagenary cycle, also known as the Stems-and-Branches or ganzi, is a cycle of sixty terms, each corresponding to one year. Each term in the sexagenary cycle consists of two Chinese characters, the first being one of the ten Heavenly Stems and the second being one of the twelve Earthly Branches.

Zodiac sign: astrological signs are the twelve 30-degree sectors that make up Earth’s 360-degree orbit around the Sun. The astrological signs are Aries, Taurus, Gemini, Cancer, Leo, Virgo, Libra, Scorpio, Sagittarius, Capricorn, Aquarius, and Pisces. Astrologers use them to roughly correspond with the signs of the zodiac to make predictions.

2. How to use the API:

The request url is: https://chinese-lunar-calendar.p.rapidapi.com with potential 3 query parameters: date, timezone and simplified.

date(required): the solar calendar date, in format of YYYYMMDD, e.g. “20250222”.

timezone(optional): the timezone of the date parameter. It only impacts the result of solar term. All other properties are all based on the solar date, regardless whichever time zone it is. The default value is 480 , which stands for the Shanghai/Singapore/Hong Kong/Taibei timezone (UTC+8:00).The timezone value is how many minutes it deviates from UTC+0:00. Suppose your timezone is UTC+5:30, so the value of the timezone parameter is 5 * 60 + 30 = 330. E.g. “330”.

simplified(optional): indicate whether the returned results should be in Simplified Chinese which people in mainland China use, or Traditional Chinese which HK and Taiwan people use. The default value is 1. 1 stand for Simplified Chinese, 0 stands for Traditional Chinese.

Sample requests:
https://chinese-lunar-calendar.p.rapidapi.com/?date=20230124&timezone=480&simplified=1
https://chinese-lunar-calendar.p.rapidapi.com/?date=20230124
https://chinese-lunar-calendar.p.rapidapi.com/?date=20230124&timezone=330

3. How to interpret responses

All response will be json formatted strings.

status:

• 0 if there’s an error, and “msg” is the error message.
• 1 if everything is fine, and “result” contains all information about the date.

msg:

• The error message if status is 0.

result:

• It contains all relevant information about the date in Chinese lunar calendar.

solarDate:

• The input solar date, which consists of 3 subcomponents: solarYear, solarMonth, solarDay.

lunarDate:

• Its corresponding Chinese lunar calendar date, which has 4 subcomponents: lunarYear, lunarMonth, lunarDay, and isleap which indicates if it is a leap month. Examples: isleap = 1 stands for a leap month, otherwise isleap is 0.

lunarDateinChinese:

• Combined month and date in Chinese calendar. Examples: “正月十五”, “闰二月廿一”

lunarYearinChinese:

• Represents the translated lunarYear value in Chinese characters. For instance, if the lunarYear is 2023, lunarYearinChinese would be 二零二三. Please note that when obtaining a complete lunar date in Chinese for a given solar calendar date, it would be a combination of lunarYearinChinese, “年” (meaning “year” in Chinese), and lunarDate. This is due to the conventional date format in Chinese, which follows the pattern YYYYMMDD. For example, the full lunar date in Chinese would be 二零二三年六月十七 for a solar date of August 3, 2023.

sexagenaryCycle(a.k.a. Gan Zi):

• Definition: https://en.wikipedia.org/wiki/Sexagenary_cycle. Examples: “甲午”, “壬寅”

solarTerm(a.k.a. Jie Qi):

• Definition: https://en.wikipedia.org/wiki/Chinese_calendar. Examples: “立春”, “清明”. Return an empty string if it has no solar terms.

solarTerminEnglish:

• The English translation of the solar term. Return an empty string if it has no solar terms.

westernZodiacSign:

• Definition: https://en.wikipedia.org/wiki/Western_astrology. Examples: “白羊座”, “双鱼座”

westernZodiacSigninEnglish:

• The English translation of the zodiac sign.

chineseZodiacSign:

• That is Chinese zodiac sign, or Sheng Xiao. Definition here: https://en.wikipedia.org/wiki/Chinese_zodiac. Examples: “牛”, “猴”

chineseZodiacSigninEnglish:

• The English translation of the Chinese zodiac sign.

festival(in beta):

• There were more than 100 festivals in Chinese history, many of them are no longer being celebrated, so it’s hard to identify all festivals. We picked 13 of them from China standard GB/T 33661-2017. They are: 春节, 元宵节, 龙头节, 上巳节, 清明节, 端午节, 七夕节, 中元节, 中秋节, 重阳节, 腊八节, 冬至节, 除夕. They are not necessarily the most popular ones. Make your own choice when appropriate. Return an empty string if it is not a festival.

Sample responses:
a) here’s the response when the input date is invalid
{
“status”: “0”,
“msg”: “Invalid date”
}

b) here’s the response for request https://chinese-lunar-calendar.p.rapidapi.com/date=20240210
{
“status”: “1”,
“result”: {
“solarDate”: {
“solarDay”: 10,
“solarMonth”: 2,
“solarYear”: 2024
},
“lunarDate”: {
“isleap”: 0,
“lunarDay”: 1,
“lunarMonth”: 1,
“lunarYear”: 2024
},
“lunarDateinChinese”: “正月初一”,
“sexagenaryCycle”: “甲辰”,
“solarTerm”: “”,
“solarTerminEnglish”: “”,
“festival”: “春节”,
“chineseZodiacSign”: “龙”,
“chineseZodiacSigninEnglish”: “Dragon”,
“westernZodiacSign”: “水瓶座”,
“westernZodiacSigninEnglish”: “Aquarius”,
“lunarYearinChinese”: “二零二四”
}
}

4. Sample javascript code

var XMLHttpRequest = require(‘xhr2’);
var xhr = new XMLHttpRequest();

const data = null;
xhr.withCredentials = true;

xhr.addEventListener(“readystatechange”, function () {
if (this.readyState === this.DONE) {
responseinjson = JSON.parse(this.responseText);
result = responseinjson.result;
resultinjson = JSON.parse(result);
lunarDateinChinese = resultinjson.lunarDateinChinese;
console.log(lunarDateinChinese);
}
});

xhr.open(“GET”, “https://chinese-lunar-calendar.p.rapidapi.com/?date=20230124”);
xhr.setRequestHeader(“X-RapidAPI-Key”, “000000000000”); //use your own key here
xhr.setRequestHeader(“X-RapidAPI-Host”, “chinese-lunar-calendar.p.rapidapi.com”);

xhr.send(data);

5. Sample Python code

import requests
import json

url = “https://chinese-lunar-calendar.p.rapidapi.com/”

querystring = {“date”:“20230124”}

headers = {
“X-RapidAPI-Key”: “000000000000”, //use your own key here
"X-RapidAPI-Host": “chinese-lunar-calendar.p.rapidapi.com”
}

response = requests.request(“GET”, url, headers=headers, params=querystring)
responseinjson = json.loads(response.text)
result = json.loads(responseinjson[‘result’])
print(result[‘lunarDateinChinese’])

6. Sample Php code
   Unable to paste code here due to format issue, so please refer to the document here: https://docs.google.com/document/d/1wE7m4nVxkhgowY7UZpy_T4YqBUtajCksyFNtzOgT-2M/edit?usp=share_link