Home › Chinese Calendar › Chinese Almanac Day (黄历)

Chinese Almanac Day (黄历)

Computes the traditional almanac (黄历 huánglì / 通胜 tōngshèng) entries of a civil date: lunar date, stem-branches, the 建除十二神 day officer, the 黄道/黑道 twelve spirits of the day and of each double-hour, the clashing animal, 煞 direction, 岁破/月破 flags, the 彭祖百忌 taboo lines and the 28-mansion (二十八宿) of the day.

When to use

You need the almanac attributes of a date as printed in a Chinese calendar (宜忌 background): day officer, 值神, 冲煞, 彭祖百忌, auspicious hours or the day's 宿.

Do not use when: You need the lunar date or solar term only (use lunar-calendar-converter or solar-terms), a birth chart (use bazi-four-pillars), or a decision — the entries are traditional attributions, not advice.

Formula

officer = (day_branch − month_branch) mod 12; day spirit = (day_branch − 青龙 branch of month) mod 12 with 青龙 on 子 for 寅申 months, 寅 for 卯酉, 辰 for 辰戌, 午 for 巳亥, 申 for 子午, 戌 for 丑未; hourly spirit = (hour_branch − 青龙 branch of day) mod 12 with the same table applied to the day branch; clash = (day_branch + 6) mod 12; mansion = (JDN − JDN(2026-07-01) + 6) mod 28

Stem-branches, lunar date and solar terms from the calendar core (UTC+8 civil days); 建除 and 十二神 follow the 通胜 conventions listed in the formula; the 28-mansion cycle is anchored on 2026-07-01 = 箕 as confirmed by the ja.wikipedia branch/weekday table (貞享 2 = 1685-02-04 = 星) and published 2026 almanac pages. Traditional reference calculation of the Chinese calendar tradition; not a prediction and not medical, legal or financial advice.

Inputs

ParameterTypeUnitRequiredDescription
datedatedefault todayGregorian civil date in China Standard Time (1900–2100); defaults to the current UTC date.

Outputs

OutputTypeUnitDescription
weekdaystringDay of the week of the Gregorian date.
lunar_date_chinesestringChinese lunar calendar date in Chinese characters.
lunar_date_englishstringLunar year, month and day in words.
year_ganzhistringStem-branch and zodiac of the lunar year; the 立春-based year is noted when it differs.
month_ganzhistringStem-branch of the solar month (changes at each 节).
day_ganzhistringStem-branch of the day.
day_ganzhi_pinyinstringPinyin of the day stem-branch.
day_officerstringOne of the 建除十二神: index = (day branch − month branch) mod 12 over 建 除 满 平 定 执 破 危 成 收 开 闭.
day_officer_pinyinstringPinyin and English gloss of the officer.
day_officer_meaningstringWhat the almanac tradition assigns to this officer.
day_officer_typestring黄道 (除 危 定 执 成 开) or 黑道 (建 满 平 破 收 闭) by the 建除 tradition.
twelve_spiritsstringSpirit of the day from the 十二神 sequence anchored by the month branch, with its 黄道/黑道 class.
lunar_mansionstringThe day's mansion in the 28-day cycle that follows the 7-day week (角 always on Thursday).
clashstringAnimal of the branch opposite the day branch.
sha_directionstring煞南 for 申子辰 days, 煞北 寅午戌, 煞东 巳酉丑, 煞西 亥卯未.
year_breakbooleantrue when the day branch clashes the year branch (立春-based year).
month_breakbooleantrue when the day branch clashes the month branch (the 破 officer day).
pengzu_taboosstring_listThe two Peng Zu taboo lines for the day stem and day branch, with an English gloss.
auspicious_hourslistThe twelve double-hours with their hourly spirit and 黄道/黑道 class (青龙 hour set by the day branch).
auspicious_hours_summarystringThe six 黄道 hours of the day.
solar_term_contextstringCurrent and next solar term.
disclaimerstringCultural reference note.

Example

2026-09-24 (辛丑日, 丁酉月): {"date":"2026-09-24"} → {"weekday":"Thursday","lunar_date_chinese":"二〇二六年八月十四","month_ganzhi":"丁酉 (Dingyou)","day_ganzhi":"辛丑","day_ganzhi_pinyin":"Xinchou","day_officer":"定","day_officer_pinyin":"Ding (Settle)","day_officer_type":"黄道 (Huangdao) — favourable class by the 建除 tradition","twelve_spirits":"勾陈 (Gouchen, Hook Array) — 黑道 (Heidao, inauspicious)","lunar_mansion":"斗木獬 (Dou, Dipper; Wood 木 — Thursday)","clash":"冲羊 (Goat, 未): 辛丑日冲羊","sha_direction":"煞东 (East)","year_break":false,"month_break":false,"pengzu_taboos":["辛不合酱主人不尝 — Xin: do not make sauce, the host would not taste it","丑不冠带主不还乡 — Chou: do not hold a capping ceremony, the person would not return home"],"auspicious_hours_summary":"黄道吉时: 寅 卯 巳 申 戌 亥 (03:00–06:59, 09:00–10:59, 15:00–16:59, 19:00–22:59)"}

2024-02-10 Chinese New Year (甲辰日, 丙寅月): {"date":"2024-02-10"} → {"weekday":"Saturday","lunar_date_chinese":"二〇二四年正月初一","year_ganzhi":"甲辰 (Jiachen) — Dragon (龙)","month_ganzhi":"丙寅 (Bingyin)","day_ganzhi":"甲辰","day_officer":"满","day_officer_type":"黑道 (Heidao) — unfavourable class by the 建除 tradition","twelve_spirits":"金匮 (Jinkui, Golden Chest) — 黄道 (Huangdao, auspicious)","lunar_mansion":"氐土貉 (Di, Root; Earth 土 — Saturday)","clash":"冲狗 (Dog, 戌): 甲辰日冲狗","sha_direction":"煞南 (South)","year_break":false,"month_break":false,"pengzu_taboos":["甲不开仓财物耗散 — Jia: do not open the storehouse, goods would be wasted","辰不哭泣必主重丧 — Chen: do not weep, it would bring repeated mourning"]}

GET https://tttkmbb.com/api/v1/calculate/chinese-almanac?date=2026-09-24

Machine access

Sources

FAQ

Why do 黄道 by officer and by spirit disagree?

They are two separate traditions printed side by side in almanacs: 建除十二神 (twelve officers, cycle reset by the month branch) and 十二神 值神 (青龙 … 勾陈, position set by the month branch). A day can be 定 (黄道 officer) and 勾陈 (黑道 spirit) at the same time.

Which year is used for 岁破?

The 立春-based year of the 八字 tradition, so between 1 January and 立春 the previous year's branch applies; the lunar year shown with the lunar date can differ in that window.

How is the 28-mansion day found?

Modern almanacs run the 28 mansions as a fixed 28-day cycle synchronised with the week (角 木 on Thursday, 亢 金 Friday, 氐 土 Saturday, 房 日 Sunday, 心 月 Monday, 尾 火 Tuesday, 箕 水 Wednesday, then 斗 …), anchored here on 2026-07-01 = 箕.

Related calculators