BaZi Chart API (八字排盤) — Chinese Four Pillars as a JSON API

Turn any birth date and time into a complete, structured BaZi (八字) chart: the four pillars with heavenly stems and earthly branches, hidden stems, Na Yin, Ten Gods (十神), five-element distribution, day-master strength, 10-year luck cycles (大運), and the current year's pillar (流年) — all as clean JSON, in Traditional Chinese, Simplified Chinese, or English. Built on battle-tested calendar math (the 6tail lunar-typescript library), with correct lunar-calendar input, leap-month handling, and timezone conversion. Pay only per chart generated.

Keywords: 八字 · 四柱 · BaZi · Four Pillars of Destiny · Chinese astrology API · 排盤 · fortune telling API · Chinese metaphysics · 大運 · 十神 · lunar calendar conversion

Quick example

Input:

{
    "birthDatetime": "1995-08-17T14:30:00",
    "calendarType": "solar",
    "gender": "male",
    "timezone": "Asia/Hong_Kong",
    "ziHourMode": "late",
    "language": "zh-Hant",
    "includeLuckCycles": true
}

Output (abridged — every stem/branch is returned with hanzi, pinyin, element, and yin-yang):

{
    "pillars": {
        "year":  { "ganZhi": { "hanzi": "乙亥", "pinyin": "yǐ hài" },
                   "heavenlyStem": { "hanzi": "乙", "pinyin": "yǐ", "element": { "key": "wood", "label": "木" }, "yinYang": "yin",
                                     "tenGod": { "hant": "正財", "hans": "正财", "pinyin": "zhèng cái", "en": "Direct Wealth", "label": "正財" } },
                   "earthlyBranch": { "hanzi": "亥", "pinyin": "hài", "element": { "key": "water", "label": "水" }, "yinYang": "yin" },
                   "hiddenStems": [ { "hanzi": "壬", "tenGod": { "label": "食神" } }, { "hanzi": "甲", "tenGod": { "label": "偏財" } } ],
                   "naYin": { "hant": "山頭火", "hans": "山头火", "en": "Fire on the Mountain Top", "label": "山頭火" } },
        "month": { "ganZhi": { "hanzi": "甲申" }, "...": "..." },
        "day":   { "ganZhi": { "hanzi": "庚辰" }, "...": "..." },
        "hour":  { "ganZhi": { "hanzi": "癸未" }, "...": "..." }
    },
    "dayMaster": {
        "stem": { "hanzi": "庚", "pinyin": "gēng", "element": { "key": "metal", "label": "金" }, "yinYang": "yang" },
        "strength": { "value": "balanced", "label": "中和", "supportRatio": 0.391, "method": "weighted five-element count ..." }
    },
    "fiveElements": {
        "counts": { "wood": 3.5, "fire": 0.5, "earth": 2.5, "metal": 2, "water": 3 },
        "percentages": { "wood": 30.4, "fire": 4.3, "earth": 21.7, "metal": 17.4, "water": 26.1 }
    },
    "tenGods": { "year": { "label": "正財" }, "month": { "label": "偏財" }, "day": { "label": "日主" }, "hour": { "label": "傷官" } },
    "luckCycles": {
        "direction": { "value": "backward", "label": "逆行" },
        "startAge": 4,
        "startDate": "1998-09-17",
        "cycles": [
            { "index": 1, "ganZhi": { "hanzi": "癸未" }, "startAge": 4, "endAge": 13, "startYear": 1998, "endYear": 2007 },
            { "index": 2, "ganZhi": { "hanzi": "壬午" }, "startAge": 14, "endAge": 23, "startYear": 2008, "endYear": 2017 }
        ]
    },
    "currentYear": { "year": 2026, "ganZhi": { "hanzi": "丙午" }, "heavenlyStem": { "tenGod": { "label": "七殺" } } },
    "meta": {
        "localBirthDatetime": "1995-08-17T14:30:00",
        "solarDate": "1995-08-17 14:30:00",
        "lunarDate": "一九九五年七月廿二",
        "ganZhiDateTime": "乙亥 甲申 庚辰 癸未",
        "library": "lunar-typescript@1.8.6"
    }
}

Use cases

• Horoscope & astrology apps — full chart data ready to render or feed to an LLM for reading generation.
• Dating & compatibility features — compare two charts' day masters, elements, and ten-god relations (八字合婚).
• Newsletters & content generation — batch mode produces hundreds of charts in one run for personalized content.
• AI agents via MCP — Apify Actors are callable as MCP tools, so agents can compute deterministic charts instead of hallucinating calendar math.

Input

Field	Type	Default	Notes
birthDatetime	string (ISO 8601)	— required	Without a UTC offset it is local wall-clock time in timezone; with an offset/Z it is converted into timezone first.
calendarType	"solar" | "lunar"	solar	For lunar, the Y-M-D of birthDatetime are lunar-calendar numbers (no UTC offset allowed).
isLeapMonth	boolean	false	Lunar only: birth month is the leap (閏) month.
gender	"male" | "female"	— required	Determines luck-cycle direction (大運順逆).
timezone	IANA string	Asia/Hong_Kong	Applied before any pillar calculation.
ziHourMode	"late" | "early"	late	See conventions below.
language	"zh-Hant" | "zh-Hans" | "en"	zh-Hant	Label language; hanzi + pinyin always included.
includeLuckCycles	boolean	true	Include 大運.
charts	array	—	Batch mode: array of records of the same shape. Top-level single-chart fields are then ignored. One invalid record never fails the run — it yields an { "error": ... } item and processing continues.

REST API (Standby mode)

This Actor supports Actor Standby, so you can call it like a regular low-latency REST API without waiting for container start:

curl -X POST "https://<username>--bazi-chart-api.apify.actor/" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"birthDatetime": "1995-08-17T14:30:00", "gender": "male", "timezone": "Asia/Hong_Kong"}'

The response is the chart JSON (or { "results": [...] } for batch bodies). Invalid input returns HTTP 400 with { "error": "..." }.

Pricing — pay per chart

You are charged one chart-generated event per successfully computed chart — nothing else. A batch of 10 valid records = 10 events; invalid or rejected records are never charged. The same applies to Standby/API requests.

Accuracy, conventions & limitations

• Calendar math comes from lunar-typescript (the 6tail library), the de-facto standard open-source implementation; solar-term boundaries, lunar conversion, and leap months are handled by the library, not hand-rolled.
• 子時 boundary (ziHourMode) — late (default, 晚子時 convention): a birth at 23:00–23:59 keeps the current day's day pillar; early: the day pillar advances to the next day at 23:00. Births at 00:00–00:59 always use the current calendar day. The hour pillar is 子時 either way.
• Luck-cycle start (起運) uses the classic method: 3 days between birth and the governing solar term = 1 year, remainder rounded to months and days.
• Year pillar for the current year (流年) switches at 立春, per standard BaZi convention.
• Day-master strength is a simple, documented weighted five-element count (see method in the output) — a screening heuristic, not a full 旺衰/格局 analysis. Use the raw counts and ten gods for your own logic.
• True solar time is not applied: the chart uses clock time in the given IANA timezone. If you need 真太陽時, adjust birthDatetime by the birthplace's longitude correction before calling.
• Timezone conversion uses the IANA tz database (via luxon), including historical offsets and DST.

---

Built by the team behind xuanzhang.app — AI-powered Chinese metaphysics readings.