BaZi / Four Pillars (Saju) API

POST`/api/bazi`Basic

Calculate a complete BaZi / Four Pillars (Saju) chart from birth data. Returns the year, month, day, and hour pillars, the Day Master, Ten Gods, hidden stems, five-element balance, luck pillars, and a trilingual (EN / 中文 / 한국어) interpretation.

Live beta

BaZi is live and returns real data on any Advanced key (and on Basic keys), but it is still in beta: the response shape may add fields before the official launch and is not yet covered by our no-breaking-changes guarantee. We will never remove the endpoint silently. See Beta & Roadmap.

Legacy URL

Also available at /api/v1/saju — the legacy URL is still fully supported and returns the identical response.

What BaZi is

BaZi (八字, "Eight Characters"), also known as Saju (사주) in Korean tradition, is the Chinese system of Four Pillars astrology. It encodes a birth moment as four pillars — year, month, day, and hour — each built from one Heavenly Stem (天干) and one Earthly Branch (地支). The eight characters are the two characters of each pillar.

The center of the chart is the Day Master (日主) — the Heavenly Stem of the day pillar, which represents the self. Every other element in the chart is read in relation to it through the Ten Gods (十神), and the balance of the five elements (wood, fire, earth, metal, water) across the chart tells you where a person is supported and where they are drained.

Lichun-corrected year boundary

The BaZi calendar year does not start on January 1. It starts at Lìchūn (立春, "start of spring"), the solar term near February 4. A birth in late January or early February is resolved by the Sun's longitude, not the calendar date, so the year pillar is correct for people born around the boundary.

Request

The request needs birth data plus a gender (male or female), which sets the direction in which the luck pillars run. Location can be given three ways: a birthLocation city string, an explicit IANA timezone, or latitude + longitude. At least one is required.

Body Parameters

Parameter	Type	Required	Description
`birthDate`	string	Yes	Date of birth (YYYY-MM-DD)
`birthTime`	string	Yes	Time of birth (HH:MM, 24-hour format)
`gender`	string	Yes	"male" or "female" — sets the luck-pillar direction. Anything else returns 400.
`birthLocation`	string	No	Birth city (e.g. "New York, NY"). Resolves timezone and coordinates offline-first.
`timezone`	string	No	Explicit IANA timezone (e.g. "America/New_York"). Use instead of birthLocation if you already know it.
`latitude`	number	No	Latitude. Provide with longitude as an alternative to birthLocation.
`longitude`	number	No	Longitude. Provide with latitude.
`useTrueSolarTime`	boolean	No	When true, the hour pillar is computed from local apparent solar time (longitude + equation of time) instead of clock time. Default: false.

Location is required

You must supply at least one of birthLocation, timezone, or latitude + longitude. A request with none returns 400.

thd-api

Response

A successful call returns { success, meta, data }. Everything substantive lives under data. Every stem and branch carries trilingual labels — chinese (中文), korean (한국어), and english — so the same response renders in any of the three supported languages.

Response200

{
"success": true,
"meta": {
  "version": "1.0.0",
  "timestamp": "2026-06-23T10:30:00.000Z",
  "endpoint": "v1/saju"
},
"data": {
  "birthInfo": {
    "date": "1990-05-15",
    "time": "14:30",
    "timezone": "America/New_York",
    "utcOffset": -4,
    "location": "New York, NY",
    "coordinates": { "lat": 40.7128, "lon": -74.006 },
    "sunLongitude": 54.382,
    "solarMonth": 3,
    "trueSolarTime": null
  },
  "fourPillars": {
    "year": {
      "stem":   { "id": 6, "chinese": "庚", "korean": "경", "english": "Geng", "element": "metal", "polarity": "yang" },
      "branch": { "id": 6, "chinese": "午", "korean": "오", "english": "Wu", "element": "fire", "polarity": "yang", "animal": { "en": "Horse", "cn": "馬", "kr": "말" }, "season": "summer" },
      "sexagenary": 6,
      "naYin": { "english": "Road-side Earth", "chinese": "路旁土", "korean": "노방토" },
      "tenGod": { "english": "Companion", "chinese": "比肩", "korean": "비견", "abbreviation": "F", "key": "companion" }
    },
    "month": { "stem": { "...": "..." }, "branch": { "...": "..." }, "sexagenary": 18, "naYin": { "...": "..." }, "tenGod": { "...": "..." } },
    "day":   { "stem": { "...": "..." }, "branch": { "...": "..." }, "sexagenary": 30, "naYin": { "...": "..." }, "tenGod": null },
    "hour":  { "stem": { "...": "..." }, "branch": { "...": "..." }, "sexagenary": 42, "naYin": { "...": "..." }, "tenGod": { "...": "..." } }
  },
  "dayMaster": {
    "stem": { "id": 6, "chinese": "庚", "korean": "경", "english": "Geng", "element": "metal", "polarity": "yang" },
    "element": "metal",
    "polarity": "yang",
    "seasonalStrength": "weak"
  },
  "hiddenStems": {
    "year":  [{ "...": "..." }],
    "month": [{ "...": "..." }],
    "day":   [{ "...": "..." }],
    "hour":  [{ "...": "..." }]
  },
  "tenGods": {
    "year":  { "english": "Companion", "chinese": "比肩", "korean": "비견", "abbreviation": "F", "key": "companion" },
    "month": { "...": "..." },
    "day":   null,
    "hour":  { "...": "..." },
    "hidden": { "year": ["..."], "month": ["..."], "day": ["..."], "hour": ["..."] }
  },
  "fiveElements": { "wood": 1.2, "fire": 2.1, "earth": 1.0, "metal": 2.5, "water": 0.3 },
  "fiveFactors": [
    { "element": "metal", "category": { "en": "Companion", "cn": "比劫", "kr": "비겁" }, "count": 2.5, "percent": 36 },
    { "element": "fire",  "category": { "en": "Influence", "cn": "官殺", "kr": "관살" }, "count": 2.1, "percent": 30 }
  ],
  "luckPillars": {
    "direction": "forward",
    "startAge": 7,
    "pillars": [
      {
        "index": 0,
        "startAge": 7,
        "endAge": 16,
        "stem":   { "...": "..." },
        "branch": { "...": "..." },
        "naYin":  { "...": "..." },
        "element": "metal",
        "annualPillars": ["..."]
      }
    ]
  },
  "currentLuckPillar": { "index": 3, "stem": { "...": "..." }, "branch": { "...": "..." }, "ageRange": "37-46" },
  "annualPillar": { "year": 2026, "stem": { "...": "..." }, "branch": { "...": "..." }, "element": "fire" },
  "symbolicStars": {
    "peachBlossom":  { "name": "Peach Blossom", "branch": { "...": "..." }, "presentIn": ["day"] },
    "nobleman":      { "name": "Nobleman", "branches": ["..."], "presentIn": [] }
  },
  "gongmang": { "branches": ["..."], "presentIn": [] },
  "chartStrength": {
    "overall": "weak",
    "seasonalElement": "fire",
    "isSeasonallyStrong": false,
    "isSeasonallySupported": false,
    "supportScore": 3.5,
    "drainScore": 6.1
  },
  "mingGua": { "number": 4, "directions": { "...": "..." } },
  "celestialAnimal": { "branch": { "...": "..." } },
  "lifePalace": { "stem": { "...": "..." }, "branch": { "...": "..." } },
  "conceptionPalace": { "stem": { "...": "..." }, "branch": { "...": "..." } },
  "naYin": { "year": { "...": "..." }, "month": { "...": "..." }, "day": { "...": "..." }, "hour": { "...": "..." } },
  "gender": "male",
  "interactions": { "branches": { "...": "..." }, "stems": { "combinations": ["..."] } },
  "growthStages": { "...": "..." },
  "chartPattern": { "...": "..." },
  "usefulGod": {
    "useful":    { "element": "earth", "tenGod": { "...": "..." }, "chinese": "土", "korean": "토" },
    "favorable": { "...": "..." },
    "taboo":     { "...": "..." },
    "hateful":   { "...": "..." },
    "idle":      { "...": "..." }
  },
  "shenSha": ["..."],
  "dmStrengthDetail": { "...": "..." }
}
}

Top-level `data` fields

Field	Description
`birthInfo`	Echoed birth data plus resolved `timezone`, `utcOffset`, `coordinates`, `sunLongitude`, `solarMonth`, and `trueSolarTime` (`null` unless `useTrueSolarTime` was set)
`fourPillars`	The `year`, `month`, `day`, and `hour` pillars — each a `stem`, `branch`, `sexagenary` number (0-59), `naYin`, and `tenGod`
`dayMaster`	The day pillar's stem (the self): `element`, `polarity`, and `seasonalStrength`
`hiddenStems`	The stems hidden inside each pillar's Earthly Branch (藏干)
`tenGods`	The Ten God of each pillar relative to the Day Master, plus the Ten Gods of the hidden stems. The day pillar's own Ten God is `null` (it is the Day Master)
`fiveElements`	Weighted count of each element (wood / fire / earth / metal / water) across the chart
`fiveFactors`	Each element mapped to its Ten God category (Companion / Output / Wealth / Influence / Resource) with a `count` and `percent`, sorted highest-first
`luckPillars`	The 10-year luck cycles: `direction`, `startAge`, and a `pillars` array (each with nested `annualPillars` and `monthlyPillars`)
`currentLuckPillar`	The luck pillar active right now, with its `ageRange`
`annualPillar`	The pillar for the current calendar year
`symbolicStars` / `gongmang`	Classical symbolic stars (Peach Blossom, Nobleman, Traveling Horse, etc.) and the Void (空亡) branches, each marked with `presentIn`
`chartStrength`	Day Master strength analysis: `overall`, `seasonalElement`, support/drain scores
`mingGua` / `celestialAnimal` / `lifePalace` / `conceptionPalace`	Additional classical points (may be `null`)
`naYin`	The Na Yin (納音) "sound element" of each pillar

Interpretation fields

These come from the enrichment layer and provide the relational reading on top of the raw chart.

Field	Description
`interactions`	Detected Earthly Branch interactions (clashes, harmonies, three-harmonies, directional combos, punishments, harms, destructions) and Heavenly Stem combinations
`growthStages`	The twelve growth stage (十二長生) for the Day Master at each pillar's branch
`chartPattern`	The chart's overall pattern / structure descriptor
`usefulGod`	The five-god hierarchy relative to the Day Master: `useful`, `favorable`, `taboo`, `hateful`, `idle` — each an element with `tenGod`, `chinese`, and `korean` labels
`shenSha`	Array of Shen Sha (神煞) stars present in the chart with their metadata
`dmStrengthDetail`	The detailed breakdown behind the `chartStrength.overall` verdict

True solar time

Set "useTrueSolarTime": true to compute the hour pillar from local apparent solar time (longitude + equation of time) rather than clock time. This shifts the hour pillar for births near an hour boundary. The MCP tool always uses clock time (useTrueSolarTime: false); use the HTTP endpoint if you need the true-solar-time option.

MCP tool: `get_bazi_chart`

The same calculation is available over the MCP server as the get_bazi_chart tool. It takes birthDate, birthTime, birthLocation, and gender, costs the same 1 Chart request, and returns the BaZi chart as a JSON string in result.content[0].text (the same data shape as the HTTP response).

MCP argument differences

Over MCP, location is always given as birthLocation (the timezone / latitude / longitude alternatives are HTTP-only), and gender is an enum of "male" / "female". The MCP tool computes with useTrueSolarTime: false.

tools/calljson

{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
  "name": "get_bazi_chart",
  "arguments": {
    "birthDate": "1990-05-15",
    "birthTime": "14:30",
    "birthLocation": "New York, NY",
    "gender": "male"
  }
}
}

Errors & limits

Constraint	Value
Required fields	`birthDate`, `birthTime`, `gender` (missing any returns `400`)
Location	One of `birthLocation`, `timezone`, or `latitude` + `longitude` is required (`400` if none)
`gender` values	`male`, `female` (anything else returns `400`)
Required tier	`basic_chart` or `advanced_chart`
Cost	1 Chart request per call

Available on Basic keys

Unlike most Advanced endpoints, BaZi is available on Basic chart keys as well as Advanced. A key without either product receives a 403 Forbidden.