Life Manual — Chinese Astrology, BaZi & Four Pillars of Destiny API (Chinese Zodiac, Birth Chart, Feng Shui, Compatibility)

Your Chinese "life manual" from one birth date. Enter a birth date, time and city timezone and get a complete Chinese astrology profile as clean JSON: your Chinese zodiac animal + element (e.g. Fire Horse), Day Master personality archetype (The Sun, The Ocean, The Jewel...), Five Elements balance, lucky colors, numbers, directions & gemstones, Feng Shui Kua number, 2026 Year of the Fire Horse / 2027 Fire Goat forecast themes, your 10-year luck pillar, a Western sun sign crossover — and optional love compatibility with a partner. Under the hood: a full, verified BaZi / Four Pillars of Destiny (八字) chart.

🔮 Deterministic rules from classical BaZi — no LLM, no random text, no stored birth data. Same input → same output, every time.

In one sentence: Life Manual is a Chinese astrology and Chinese horoscope API that turns a birth date, time and timezone into a full BaZi birth chart (Four Pillars of Destiny, 八字, also called Saju 사주 in Korea) plus a plain-English reading: Chinese zodiac sign and element, Day Master personality test-style archetype, Five Elements (Wu Xing) balance, lucky colors, lucky numbers, lucky directions and lucky gemstones, Feng Shui Kua number, a yearly horoscope for 2026 Year of the Fire Horse and 2027 Year of the Fire Goat (Tai Sui), 10-year luck pillars, Western zodiac sun sign crossover, and love compatibility / couple compatibility for dating apps.

✨ What you get (one row per person — pick modules, or take the Full Life Manual)

Feature	Output field	Example
Chinese zodiac animal + element, traits, best matches, clash	zodiacProfile	Metal Horse · best: Goat, Tiger, Dog · clashes: Rat
Day Master personality (10 archetypes)	dayMasterProfile	Yang Metal "The Sword / Axe" — strengths, challenges, career affinities
Five Elements balance & Day Master strength	elementBalance	Fire dominant, Wood weakest · favourable: Wood, Water
Lucky colors / numbers / directions / gemstones / seasons	luckyCharms	green, navy · 3, 8, 1, 6 · East, North · jade, obsidian
Feng Shui Kua number (Eight Mansions)	fengShuiKua	Kua 1 (East group) · Sheng Qi = SE
2026 & 2027 yearly forecast themes, Tai Sui	forecast.thisYear/nextYear	2026 Fire Horse: Ben Ming year (Tai Sui)
Current & next 10-year luck pillar in plain English	forecast.currentLuckPillar	2017–2026: opportunities, windfalls, networking
Western zodiac crossover	westernCrossover	Metal Horse × Taurus
💞 Compatibility (with partner input)	compatibility	score 0–100, zodiac + Day Master + spouse-palace relations
Full BaZi chart: pillars, ten gods, hidden stems, luck pillars (大运), annual pillars (流年), shen sha (神煞), lunar date	pillars, daYun, liuNian, shenSha...	庚午 辛巳 庚辰 壬午

Sample output (abridged)

{
  "fourPillars": "庚午 辛巳 庚辰 壬午",
  "zodiacProfile": { "label": "Metal Horse", "traits": "Energetic, free-spirited and warm; loves movement and adventure.",
                     "bestMatches": ["Goat", "Tiger", "Dog"], "clashesWith": "Rat" },
  "dayMasterProfile": { "archetype": "The Sword / Axe", "element": "Yang Metal", "strength": "balanced",
                        "careerAffinities": ["engineering", "sports", "surgery", "operations"] },
  "elementBalance": { "dominantElement": "Fire", "weakestElement": "Wood", "favorableElements": ["Wood", "Water"] },
  "luckyCharms": { "colors": ["green", "teal", "black", "navy"], "numbers": [3, 8, 1, 6], "directions": ["East", "Southeast", "North"] },
  "fengShuiKua": { "number": 1, "group": "East" },
  "westernCrossover": { "sunSign": "Taurus", "eastWestLabel": "Metal Horse x Taurus with a Yang Metal Day Master" },
  "forecast": { "thisYear": { "label": "Fire Horse", "tenGod": "七杀",
                "taiSui": "Ben Ming Nian: your own zodiac year (Tai Sui year) - traditionally a year to stay humble and steady." } },
  "compatibility": { "score": 68, "label": "moderate", "dayMasterRelation": "generating cycle (Earth nourishes Metal)" }
}

🔎 Chinese astrology terms this Actor covers (glossary)

• Chinese astrology / Chinese horoscope / Eastern astrology: the classical Chinese metaphysics (Mingli, 命理) system of reading a birth chart from the Chinese calendar.
• BaZi, Four Pillars of Destiny, Saju: the year, month, day and hour pillars of a birth chart (natal chart) written in heavenly stems and earthly branches. BaZi (Chinese) and Saju (Korean) use the same Four Pillars, which this Actor computes.
• Chinese zodiac sign: your animal sign (Rat, Ox, Tiger, Rabbit, Dragon, Snake, Horse, Goat/Sheep, Monkey, Rooster, Dog, Pig) plus its element, e.g. Fire Horse or Water Rabbit, with personality traits, best zodiac compatibility matches and clashes.
• Day Master: the day stem that represents you; mapped to ten personality archetypes (a personality test for astrology fans) with strengths, challenges and career ideas.
• Five Elements / Wu Xing: Wood, Fire, Earth, Metal and Water balance of the chart, element strength and favourable elements.
• Lucky colors, lucky numbers, lucky directions, lucky gemstones and crystals: derived from your favourable elements.
• Feng Shui Kua number: the Eight Mansions life gua with four lucky and four unlucky directions for home and desk placement.
• Yearly horoscope and Tai Sui: 2026 Year of the Horse (Fire Horse) and 2027 Year of the Goat (Fire Goat) themes for Chinese New Year content, including Ben Ming Nian (your own zodiac year).
• Luck pillars (Da Yun) and annual pillars (Liu Nian): 10-year destiny cycles and year-by-year pillars.
• Love compatibility / synastry-style match: compares two BaZi charts (zodiac, spouse palace, Day Master and elements) and returns a 0–100 love match score for couples, friends and dating apps.
• Western zodiac crossover: your sun sign (e.g. Taurus, Leo) combined with your Chinese zodiac sign, e.g. Metal Horse × Taurus.
• Chinese lunar calendar: accepts lunar birth dates (with leap months) and returns the lunar date, solar terms, ten gods, shen sha (symbolic stars) and hidden stems.

Not included: this Actor does not do tarot, I Ching, numerology life path numbers, Zi Wei Dou Shu (Purple Star astrology / Tu Vi) or Western natal chart planets. It pairs well with spiritual, tarot and numerology apps that want a Chinese birth chart layer.

❓ FAQ

• Is this a Chinese horoscope API or a BaZi calculator? Both: a BaZi / Four Pillars calculator underneath, with ready-to-show Chinese horoscope, zodiac and fortune-telling-style texts on top.
• What is my Chinese zodiac sign? The year pillar decides it, switching at Lichun (around Feb 4), not on Jan 1. Life Manual handles that boundary exactly.
• Can I use it for a dating app or couple compatibility quiz? Yes. Add a partner to get a love compatibility score with reasons.
• Does it work for Korean Saju? It returns the same Four Pillars (stems and branches, ten gods, luck pillars); readings are written in English with Chinese terms.
• Is it fortune telling? It is for entertainment, cultural education and self-reflection; texts are fixed rules, not predictions.
• Can AI agents call it? Yes, via the Apify MCP server (Claude, Cursor, ChatGPT and other MCP clients).

🚀 Use cases

• Astrology & horoscope apps / websites — instant "Chinese zodiac + BaZi reading" pages, daily/yearly content
• Discord / Telegram / WhatsApp bots — /myzodiac, /luckycolor, /compatibility commands
• Personality quizzes & dating apps — Day Master archetypes and love-match scores
• Content creators — batch 500 charts for Year of the Horse 2026 videos, newsletters, personalised readings
• AI agents, ChatGPT/Claude tools & MCP clients — give your agent a correct chart and rule-based facts instead of hallucinated calendar math
• Feng Shui & wellness brands — Kua directions, lucky elements and colors for product recommendations
• Spiritual, metaphysics & esoteric apps — add a Chinese astrology birth chart next to tarot or numerology features
• Chinese New Year campaigns — Year of the Horse 2026 and Year of the Goat 2027 zodiac content at scale

💵 Pricing — pay only for the modules you pick (Start at $0.30 · Full Life Manual from $1.99)

Module (modules value)	What you get	Price per chart
basic-chart (always included)	Four Pillars, ten gods, hidden stems, luck & annual pillars, shen sha, lunar date	$0.30
zodiac-profile	Zodiac animal + element, traits, best matches, clash	$0.30
day-master-profile	Day Master personality archetype, strengths, challenges, careers	$0.50
element-balance-lucky	Five Elements balance + lucky colors, numbers, directions, gemstones	$0.50
feng-shui-kua	Kua number, 4 lucky + 4 unlucky directions	$0.30
western-crossover	Western sun sign × Chinese zodiac (e.g. Metal Horse × Taurus)	$0.20
forecast	Current/next 10-year luck pillar + 2026 Fire Horse & 2027 Fire Goat themes	$1.00
compatibility (needs partner)	0–100 love/friendship match score with reasons	$1.50
⭐ Full Life Manual ("plan": "full", no partner)	Every module except compatibility (basic chart + zodiac + Day Master + elements & lucky charms + Feng Shui Kua + Western crossover + forecast)	$1.99 — best value, save ~36% vs $3.10 à la carte
💞 Full Life Manual + Love ("plan": "full" + partner)	Everything above, including love compatibility	$2.99 — save ~35% vs $4.60 à la carte

• Default (no modules given): basic chart + zodiac profile = $0.60 per chart — a cheap first try.
• With "plan": "full" you are charged only one bundle event per chart — full-life-manual ($1.99) without a partner, or full-life-manual-love ($2.99) when you add a partner — never the individual modules on top.
• 💞 Compatibility is built for dating apps, couple quizzes and "are we a match?" content — one call returns both charts' match score and reasons.
• Rows with an input error are free. Your max charge per run is respected: the Actor stops cleanly when the limit is reached.
• Actor start: Apify platform minimum ($0.00005).

🤖 Use with AI agents (MCP) — Claude, Cursor, VS Code, ChatGPT

Life Manual works as a ready-made tool for AI agents through the official Apify MCP server (mcp.apify.com). Your agent gets one tool, awake_froghopper--chinese-bazi-four-pillars, with the full input schema, so it can compute a correct chart instead of guessing calendar math.

Claude Desktop / claude.ai: Settings → Connectors → Add custom connector → Remote MCP server URL:

https://mcp.apify.com?tools=awake_froghopper/chinese-bazi-four-pillars

Sign in to Apify in the browser window on first connect (OAuth, no token in the config).

Cursor, VS Code and other JSON-config clients (e.g. Cursor ~/.cursor/mcp.json) — hosted server with OAuth:

{
  "mcpServers": {
    "life-manual": {
      "url": "https://mcp.apify.com?tools=awake_froghopper/chinese-bazi-four-pillars"
    }
  }
}

With an API token instead of OAuth (token from Apify Console → API & Integrations):

{
  "mcpServers": {
    "life-manual": {
      "url": "https://mcp.apify.com?tools=awake_froghopper/chinese-bazi-four-pillars",
      "headers": { "Authorization": "Bearer <APIFY_TOKEN>" }
    }
  }
}

Local stdio (clients without remote MCP support; the current server needs Node.js 22+):

{
  "mcpServers": {
    "life-manual": {
      "command": "npx",
      "args": ["-y", "@apify/actors-mcp-server@latest", "--tools", "awake_froghopper/chinese-bazi-four-pillars"],
      "env": { "APIFY_TOKEN": "<APIFY_TOKEN>" }
    }
  }
}

• Want discovery tools too? Use https://mcp.apify.com?tools=actors,docs,awake_froghopper/chinese-bazi-four-pillars, or pick tools visually in the MCP configurator.
• Example prompt: "Use Life Manual to read my Chinese zodiac and lucky colors: born 1990-05-15 12:00 in New York, male." — the agent fills birthDate, birthTime, gender, timezone: America/New_York.
• Ask the agent for "plan": "full" for the complete reading, or add a partner for love compatibility. Pricing is the same as normal runs (default call = $0.60).
• The tool returns run info plus a datasetId; the agent reads the rows with get-dataset-items (added automatically).

Why it is accurate

• Year pillar / zodiac switches at the exact Lichun instant (~Feb 4) — not Jan 1 or Lunar New Year; month pillar at exact solar terms
• Any birth city timezone worldwide, historical daylight saving time, optional true solar time from longitude
• Gregorian or Chinese lunar date input, leap months, Zi-hour options (子初换日 / 早晚子时)
• Cross-checked against an independent BaZi engine on 400 random charts
• Batch up to 500 people per run; per-row errors
• 🔒 No LLM, no external API calls, birth data is never logged or stored outside your own run's dataset; set includeInputEcho=false to drop it there too

Disclaimer. For entertainment, cultural education and self-reflection only. BaZi and Chinese astrology are traditional metaphysical systems, not science. Readings are fixed rule-based texts, not predictions, and are not medical, financial, legal, psychological or relationship advice.

Method notes (transparent rules)

• Favourable elements: weighted Five Elements count (stems 1.0, hidden stems 1.0/0.5/0.3, month branch ×2). Support ratio ≥ 0.55 = strong Day Master → output/wealth/officer elements favourable; ≤ 0.42 = weak → resource/companion; otherwise balanced → the weakest elements. Lucky colors (五行色), Hetu numbers (河图数) and directions follow the favourable elements.
• Kua: Eight Mansions formula from the BaZi year and gender.
• Forecast: ten-god theme of the year/luck stem, element tone vs. favourable elements, and Tai Sui relation (same / clash / harm / harmony) with your zodiac.
• Compatibility: base 60; zodiac relation, spouse-palace (day branch) relation, Day Master stem relation (五合 / generating / controlling) and mutual favourable elements; full breakdown returned.

How to run

1. Open Life Manual on Apify Store
2. Paste one of the JSON examples below into Input
3. Click Start — results land in the default dataset (one row per person)

Or call the API / Actor client with the same JSON body.

Copy-paste input examples

0) ⭐ Full Life Manual ($1.99, best value)

{
  "plan": "full",
  "birthDate": "1990-05-15", "birthTime": "12:00", "gender": "male", "timezone": "America/New_York"
}

0a) 💞 Full Life Manual + Love compatibility ($2.99)

{
  "plan": "full",
  "birthDate": "1990-05-15", "birthTime": "12:00", "gender": "male", "timezone": "America/New_York",
  "partner": { "birthDate": "1991-07-10", "birthTime": "10:00", "gender": "female", "timezone": "Europe/London" }
}

0b) Pick modules (custom: $0.30 + $0.50 + $1.00 = $1.80)

{ "birthDate": "1995-02-10", "birthTime": "08:15", "gender": "female", "timezone": "Europe/London",
  "modules": ["day-master-profile", "forecast"] }

1) Single chart (Gregorian, China)

{
  "birthDate": "1990-05-15",
  "birthTime": "12:00",
  "gender": "male",
  "timezone": "Asia/Shanghai"
}

2) True solar time (New York) + specific annual years

{
  "birthDatetime": "1988-07-01T09:05:00-04:00",
  "gender": "female",
  "longitude": -74.0,
  "solarTime": "trueSolar",
  "liuNianYears": [2026, 2027, 2028]
}

3) Batch + Chinese lunar calendar date

{
  "people": [
    {
      "id": "gregorian-a",
      "birthDate": "1990-05-15",
      "birthTime": "12:00",
      "gender": "male",
      "timezone": "+08:00"
    },
    {
      "id": "lunar-b",
      "birthDate": "1990-04-21",
      "birthTime": "08:30",
      "gender": "female",
      "calendar": "lunar",
      "lunarLeapMonth": false,
      "timezone": "Asia/Shanghai"
    }
  ],
  "includeInputEcho": false
}

Set includeInputEcho to false to keep raw birth date/time out of result rows.

Main input fields

Field	Default	Notes
birthDate	—	YYYY-MM-DD (Gregorian, or lunar if calendar = lunar)
birthTime	—	HH:MM local clock. Empty = unknown hour pillar
plan	custom	custom = charge per selected module; full = Full Life Manual bundle ($1.99 without partner; $2.99 with partner, adds compatibility)
modules	["zodiac-profile"]	Modules on top of the always-included basic chart (see Pricing)
partner	—	Second person {birthDate, birthTime, gender, timezone} — needed for compatibility
gender	male	male / female — luck-pillar direction
timezone	Asia/Shanghai	IANA name or offset (+08:00)
birthDatetime	—	ISO alternative, e.g. 1990-05-15T12:00:00+08:00
calendar / lunarLeapMonth	gregorian / false	Chinese lunar calendar input
solarTime	clock	clock, meanSolar, trueSolar (needs longitude)
longitude	—	Decimal degrees, east positive
ziHourRule	nextDayAt23	or sameDayLateZi
applyDst	true	false if the recorded time is already standard time
qiYunMethod	days	days (3 days = 1 year) or minutes
daYunCount	8	1–12 luck pillars
liuNianFrom / liuNianTo / liuNianYears	current year +4	Annual pillars
people	—	Batch array (same fields + optional id)
includeInputEcho	true	false omits raw birth data from dataset rows

Output (one row per person, abbreviated)

{
  "id": "a",
  "fourPillars": "庚午 辛巳 庚辰 壬午",
  "dayMaster": { "stem": "庚", "pinyin": "Geng", "element": "Metal", "yinYang": "yang" },
  "pillars": {
    "month": {
      "ganzhi": "辛巳",
      "stemTenGod": "劫财",
      "stemTenGodEn": "Rob Wealth",
      "hiddenStems": [
        { "stem": "丙", "tenGod": "七杀" },
        { "stem": "庚", "tenGod": "比肩" },
        { "stem": "戊", "tenGod": "偏印" }
      ],
      "nayin": "白蜡金",
      "lifeStage": "长生"
    }
  },
  "fiveElements": {
    "visibleCounts": { "Wood": 0, "Fire": 3, "Earth": 1, "Metal": 3, "Water": 1 },
    "missingVisible": ["Wood"]
  },
  "daYun": {
    "direction": "forward",
    "startDateUtc8": "1997-08-15",
    "pillars": [{ "index": 1, "ganzhi": "壬午", "startYear": 1997, "endYear": 2006 }]
  },
  "liuNian": [{ "year": 2026, "ganzhi": "丙午", "stemTenGod": "七杀" }],
  "shenSha": [{ "name": "天乙贵人", "nameEn": "Heavenly Noble (Tian Yi)" }],
  "voidBranches": ["申", "酉"],
  "conventions": { "ziHourRule": "Day changes at 23:00 (zi chu)..." },
  "warnings": [],
  "disclaimer": "For cultural, educational and entertainment purposes only. ..."
}

Method notes

• Year / month pillars from the birth instant vs solar-term instants (China Standard Time, UTC+8). Births within 2 hours of a jie get a warning.
• Day / hour pillars use local time: clock (DST removed), mean solar, or true solar from longitude.
• Luck pillars: yang-year male / yin-year female go forward; others backward. Ages are nominal (虚岁).
• Shen sha: 22 common stars; only those present are listed, with lookup basis in conventions.
• Supported birth years: 1800–2100.

Accuracy

Anchor tests cover published charts (e.g. 1893-12-26 辰时; 1866-11-12 寅时), Lichun and zi-hour edges, China’s 1986–1991 DST, true solar time and lunar leap months. 400 random charts (1901–2099) were cross-checked against an independent MIT-licensed engine: identical pillars, luck direction, first luck pillar and shen sha.

Privacy

No LLM. No external calls. Birth data is not logged and nothing is kept after the run beyond your own Apify dataset (your retention settings). Use includeInputEcho: false to keep raw birth fields out of result rows.

Credits

Calendar math: lunar-python (MIT). Shen sha tables adapted from bazi-skill (MIT). See THIRD_PARTY_NOTICES.md.

---

中文简介（人生说明书 · 八字排盘）

确定性的四柱八字排盘 API：输入出生日期、时间、性别、时区，输出四柱、十神（含藏干）、五行、纳音、十二长生、大运、流年、神煞、空亡、胎元。年柱以立春精确时刻分界，月柱以十二节分界；支持真太阳时、早晚子时、任意时区与历史夏令时、农历（含闰月），可批量排盘。不用大模型，不保存出生信息。按模块计费：基础盘 $0.30 起，全套 Full Life Manual $1.99（不含合盘）/ 含合盘 $2.99。仅供传统文化学习与娱乐参考。