# 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.

- Calculator id: `chinese-almanac` · Category: Chinese Calendar (`lunar`) · Tool name: `describe_chinese_almanac_day`
- Canonical page: https://tttkmbb.com/lunar/chinese-almanac · This document: https://tttkmbb.com/lunar/chinese-almanac.md · JSON definition: https://tttkmbb.com/lunar/chinese-almanac.json

## Purpose

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.

**Use when:** 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.

## Input

| Parameter | Type | Unit | Required | Description |
| --- | --- | --- | --- | --- |
| `date` | date |  | optional, default "today" | Gregorian civil date in China Standard Time (1900–2100); defaults to the current UTC date. |

## Output

| Field | Type | Unit | Description |
| --- | --- | --- | --- |
| `weekday` | string |  | Day of the week of the Gregorian date. |
| `lunar_date_chinese` | string |  | Chinese lunar calendar date in Chinese characters. |
| `lunar_date_english` | string |  | Lunar year, month and day in words. |
| `year_ganzhi` | string |  | Stem-branch and zodiac of the lunar year; the 立春-based year is noted when it differs. |
| `month_ganzhi` | string |  | Stem-branch of the solar month (changes at each 节). |
| `day_ganzhi` | string |  | Stem-branch of the day. |
| `day_ganzhi_pinyin` | string |  | Pinyin of the day stem-branch. |
| `day_officer` | string |  | One of the 建除十二神: index = (day branch − month branch) mod 12 over 建 除 满 平 定 执 破 危 成 收 开 闭. |
| `day_officer_pinyin` | string |  | Pinyin and English gloss of the officer. |
| `day_officer_meaning` | string |  | What the almanac tradition assigns to this officer. |
| `day_officer_type` | string |  | 黄道 (除 危 定 执 成 开) or 黑道 (建 满 平 破 收 闭) by the 建除 tradition. |
| `twelve_spirits` | string |  | Spirit of the day from the 十二神 sequence anchored by the month branch, with its 黄道/黑道 class. |
| `lunar_mansion` | string |  | The day's mansion in the 28-day cycle that follows the 7-day week (角 always on Thursday). |
| `clash` | string |  | Animal of the branch opposite the day branch. |
| `sha_direction` | string |  | 煞南 for 申子辰 days, 煞北 寅午戌, 煞东 巳酉丑, 煞西 亥卯未. |
| `year_break` | boolean |  | true when the day branch clashes the year branch (立春-based year). |
| `month_break` | boolean |  | true when the day branch clashes the month branch (the 破 officer day). |
| `pengzu_taboos` | string_list |  | The two Peng Zu taboo lines for the day stem and day branch, with an English gloss. |
| `auspicious_hours` | list |  | The twelve double-hours with their hourly spirit and 黄道/黑道 class (青龙 hour set by the day branch). |
| `auspicious_hours_summary` | string |  | The six 黄道 hours of the day. |
| `solar_term_context` | string |  | Current and next solar term. |
| `disclaimer` | string |  | Cultural reference note. |

## 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.

## Data Sources

- Tung Shing / 通勝 almanac (Wikipedia) — https://en.wikipedia.org/wiki/Tung_Shing (reference, retrieved 2026-09-24)
- 二十八宿 – weekday cycle and 貞享 anchor (Wikipedia, Japanese) — https://ja.wikipedia.org/wiki/二十八宿 (reference, retrieved 2026-09-24)
- Chinese calendar – rules of GB/T 33661-2017 (Wikipedia) — https://en.wikipedia.org/wiki/Chinese_calendar (reference, retrieved 2026-09-24)

Data freshness: `daily` (max_age_seconds 86400). Depends on the current date.

## API

- `GET https://tttkmbb.com/api/v1/calculate/chinese-almanac?`
- `POST https://tttkmbb.com/api/v1/calculate/chinese-almanac` with JSON body `{"inputs": {…}}`
- Response: unified envelope (`success`, `request`, `result.values`, `result.units`, `sources`, `freshness`, `timestamp`, `next_actions`, `links`); see https://tttkmbb.com/docs/response-format.md
- Schema: https://tttkmbb.com/api/v1/calculators/chinese-almanac · OpenAPI operationId `describe_chinese_almanac_day` in https://tttkmbb.com/openapi.json
- Authentication: none. Rate limit: fair use, see https://tttkmbb.com/docs/rate-limits.md.

## MCP

- Server: `https://tttkmbb.com/mcp` (Streamable HTTP, JSON-RPC 2.0, no auth)
- Tool:  `run_calculator` with `{"calculator_id": "chinese-almanac", "inputs": {…}}`

## Example

- 2026-09-24 (辛丑日, 丁酉月): inputs `{"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 (甲辰日, 丙寅月): inputs `{"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
```

## Limitations

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. 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. All values are computed from the formula above; no measurement or live data is involved.

## 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

- [Lunar Calendar Converter (农历)](https://tttkmbb.com/lunar/lunar-calendar-converter.md) — Full lunar date conversion for the same day.
- [Bazi Four Pillars (八字)](https://tttkmbb.com/lunar/bazi-four-pillars.md) — Birth chart built from the same stem-branch cycle.
- [24 Solar Terms Calculator (二十四节气)](https://tttkmbb.com/lunar/solar-terms.md) — Dates of the 24 solar terms that set the month branch.