BaZi API for Developers: Four Pillars, Three Conventions

Two BaZi calculators handed the same birth date, time and place will often disagree about the chart, and the disagreement is almost never an arithmetic bug. It is a convention. Three switches sit under every Four Pillars engine: which instant starts the sexagenary day, which instant starts the sexagenary year, and which clock the hour branch is read from. Most tools pick one setting for each, hide the choice, and print a chart. When a user brings a chart drawn by a practitioner, you cannot tell whether you disagree about the math or about the school. So the first question to ask of any BaZi API is not how accurate it is. It is whether you can reproduce a chart somebody else already published.

What should a BaZi API return for one birth?

One request carrying a birth date, time and timezone should return all four pillars complete, plus the Day Master, the element distribution, the branch interactions and the conventions the chart was computed under. A pillar is not two characters. Each one carries a stem, a branch, the stems hidden inside that branch, the Ten God relation to the Day Master, and its Na Yin pairing.

Here is the day pillar from a live POST /chinese-astrology/bazi/chart response for a birth on 15 June 1990 at 23:30 under timezone Asia/Shanghai, trimmed to the fields above:

{
  "position": "day",
  "id": "xin-hai",
  "number": 48,
  "stem": { "id": "xin", "chinese": "辛", "element": "Metal", "polarity": "yin" },
  "branch": { "id": "hai", "chinese": "亥", "animal": "pig", "element": "Water" },
  "tenGod": { "id": "day-master", "name": "Day Master", "category": "self" },
  "hiddenStems": [
    { "stem": "ren", "element": "Water", "role": "principal", "tenGod": "Hurting Officer" },
    { "stem": "jia", "element": "Wood", "role": "middle", "tenGod": "Direct Wealth" }
  ],
  "naYin": "Metal of Hairpin and Bracelet",
  "naYinChinese": "釵釧金",
  "naYinElement": "Metal"
}

Ready to run these checks yourself? The Chinese Astrology API returns the complete Four Pillars chart in one call, one of 209+ endpoints across 14 insight domains on a single key. See pricing.

Why do two BaZi calculators disagree about the same birth?

Because three rules differ between schools, and most software hides which one it picked. The sexagenary day can turn at 23:00 or at midnight. The sexagenary year can turn at Beginning of Spring or at Lunar New Year. The hour branch can be read from the civil clock or from the sun over the birthplace. RoxyAPI makes each one a typed request field with a named default and returns the values that applied.

The year boundary is the switch consumers hit most often, because the animal people quote is folk usage and the animal a BaZi chart uses is not. A birth on 14 February 2026 at 09:00 under timezone Asia/Shanghai returns year pillar bing-wu, a Fire Horse, under li-chun. The same request under lunar-new-year returns yi-si, a Wood Snake. Neither is a bug. What matters is that the response names the rule that produced it, so two systems can be compared instead of argued about.

What does switching the day boundary actually move?

A birth at 23:30 is where the three day-boundary schools separate, and the difference is not cosmetic: it can change the Day Master, which is the subject the entire reading is about. Sending the same 1990-06-15 23:30 birth three times, changing only dayBoundary, returns three charts whose year and month pillars are identical and whose day and hour pillars are not.

{
  "conventions": { "dayBoundary": "split-zi", "yearBoundary": "li-chun", "hourClock": "clock" },
  "pillars": [
    { "position": "day",  "id": "xin-hai", "number": 48 },
    { "position": "hour", "id": "geng-zi", "number": 37 }
  ]
}
{
  "conventions": { "dayBoundary": "midnight", "yearBoundary": "li-chun", "hourClock": "clock" },
  "pillars": [
    { "position": "day",  "id": "xin-hai", "number": 48 },
    { "position": "hour", "id": "wu-zi",   "number": 25 }
  ]
}
{
  "conventions": { "dayBoundary": "early-zi", "yearBoundary": "li-chun", "hourClock": "clock" },
  "pillars": [
    { "position": "day",  "id": "ren-zi", "number": 49 },
    { "position": "hour", "id": "geng-zi", "number": 37 }
  ]
}

Under split-zi and midnight the Day Master stays yin Metal and only the hour stem moves. Under early-zi the whole day turns at 23:00, so the Day Master becomes yang Water and every Ten God in the chart is recomputed against a different subject. A reading built on the wrong switch is not slightly off. It is about somebody else.

How do you read Day Master strength without a black box?

Strength decides which elements help a chart and which drain it, so a bare verdict string is the least useful thing an API can return. POST /chinese-astrology/bazi/day-master publishes the three classical factors separately, month command, rooting and party support, each with its own signed contribution, and the three sum to score. The weighting and the five verdict bands are ours, stated as such, so you can re-weight instead of trusting a number.

For the same birth under the default split-zi, the factors come back as month command -2 (Metal is dead in a Fire month), rooting 0 (no branch stores Metal, so the day stem is rootless) and party support 1.4. They total -0.6, a balanced verdict, and favorableElements and unfavorableElements both return empty rather than inventing a preference for a chart that sits in the middle.

Luck pillars carry the same honesty. POST /chinese-astrology/bazi/luck-pillars requires gender, because the direction rule depends on it and cannot be derived from the chart. The same 1990 birth returns direction: forward with startAge: 7 for male and direction: reverse with startAge: 3 for female, each naming the boundaryTerm it counted to.

How do you call the BaZi endpoints from code?

Send date, time and timezone and the four pillars come back. Latitude and longitude are optional and do not affect a chart under the default clock hour reading. Prefer an IANA timezone name over a numeric offset: the name resolves to the correct offset for the birth date, including historical daylight-saving periods a fixed number gets wrong.

curl -s -X POST https://roxyapi.com/api/v2/chinese-astrology/bazi/chart \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_KEY" \
  -d '{"date":"1990-06-15","time":"23:30:00","timezone":"Asia/Shanghai","dayBoundary":"early-zi"}'

const res = await fetch('https://roxyapi.com/api/v2/chinese-astrology/bazi/chart', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'X-API-Key': 'YOUR_KEY' },
  body: JSON.stringify({
    date: '1990-06-15', time: '23:30:00',
    timezone: 'Asia/Shanghai', dayBoundary: 'early-zi',
  }),
});
const chart = await res.json();
console.log(chart.conventions, chart.dayMaster.element);

import requests

r = requests.post(
    'https://roxyapi.com/api/v2/chinese-astrology/bazi/chart',
    headers={'X-API-Key': 'YOUR_KEY'},
    json={'date': '1990-06-15', 'time': '23:30:00',
          'timezone': 'Asia/Shanghai', 'dayBoundary': 'early-zi'},
)
chart = r.json()
print(chart['conventions'], chart['pillars'][2]['id'])

hourClock values of local-mean and solar read the hour from the sun over the birthplace, so they need longitude and return a 400 naming the missing field without it. Resolve the birthplace first rather than asking a user for coordinates: GET /location/search?q=Chongqing returns longitude: 106.5577 and timezone: "Asia/Shanghai". Feeding that longitude into the same 23:30 birth moves the hour pillar from geng-zi to ji-hai, because Chongqing sits far west of its zone meridian.

Full request and response schemas for the 16+ routes in this domain sit in the API reference, where the playground returns real production responses in the browser with no signup and no key. Every endpoint is also a tool on the Remote MCP server at /mcp/chinese-astrology, over Streamable HTTP with no local process to run: post_chinese_astrology_bazi_chart, post_chinese_astrology_bazi_luck_pillars and post_chinese_astrology_bazi_day_master. Your agent grounds each reply in the calculation and answers in your own prompt and voice, so it never invents a pillar. Client setup lives in the MCP documentation, and typed SDKs for TypeScript, Python, PHP, C# and Go regenerate from the live spec.

What does this BaZi API not do, and what does it cost?

Two honest gaps. There is no shen sha layer today, so the symbolic stars some readings lean on are not in the response. And the interpretive text is a structured summary per pillar, element and interaction rather than a long narrative reading, which suits a product that composes its own copy and suits a reader who wants prose less well.

Pricing is flat and request based: one call is one unit whatever it computes, so a full chart and a zodiac lookup cost the same. Starter is $39 per month for 50,000 requests with every domain included, about $2.32 per domain on annual billing across 14 domains. Credit wallets that weight a heavy call more than a light one tax exactly the endpoint your product is built on. The honest counterpoint: if you need one static feature, are willing to read the classical sources yourself, and accept the calendar work, a small in-house engine can win. The months go into solar-term instants, the day-boundary and hour-clock rules, and proving your output against charts somebody already published.

FAQ

What is a BaZi API?

A BaZi API turns a birth date, time and timezone into the Four Pillars of Destiny: a Heavenly Stem and Earthly Branch for the year, month, day and hour, plus the Day Master and the relations between them. The RoxyAPI Chinese Astrology API returns all four pillars with hidden stems, Ten Gods and Na Yin in one call, plus luck pillars, Day Master strength and compatibility.

Why do BaZi calculators give different charts for the same birth?

Because they apply different school conventions and rarely say which. The day can turn at 23:00 or midnight, the year at Beginning of Spring or Lunar New Year, and the hour can be read from clock time or true solar time. RoxyAPI exposes all three as dayBoundary, yearBoundary and hourClock and echoes the values used in a conventions object, so a chart can be reproduced rather than guessed at.

Does the Chinese zodiac year start at Chinese New Year or Li Chun?

Both rules are in use, which is why it is a parameter. Folk usage starts the animal year at Lunar New Year; classical Four Pillars practice starts the sexagenary year at Beginning of Spring in early February. On RoxyAPI the BaZi endpoints default to li-chun and the folk zodiac route defaults to lunar-new-year, and every response names the rule it applied.

Why does a luck pillars endpoint need gender?

The direction of the ten-year cycles is set by the polarity of the year stem together with gender, so it cannot be derived from the chart alone. POST /chinese-astrology/bazi/luck-pillars takes a gender field and returns direction, the starting age in years and months, and the solar term it counted to, so you can check the arithmetic instead of accepting the result.

Is there a BaZi MCP server for AI agents?

Yes. RoxyAPI runs a Remote MCP server at /mcp/chinese-astrology over Streamable HTTP, so agents in Claude, ChatGPT, Gemini, n8n or Dify call tools such as post_chinese_astrology_bazi_chart with an API key and no local setup. The same key reaches Four Pillars, Western astrology and Vedic charts without a second integration.

Conclusion

A Four Pillars engine is easy to make plausible and hard to make reproducible, and reproducibility is what a support ticket about a practitioner chart actually needs. Judge a BaZi API on that: run one birth at 23:30 through all three day-boundary values against the Chinese Astrology API and read the conventions block that comes back. One key covers Four Pillars, luck pillars and Day Master strength alongside Western astrology, Vedic, forecast and ten more insight domains.