---
title: "Calculate Four Pillars of Destiny (BaZi)"
method: POST
path: "/chinese/bazi"
tags: ["chinese"]
---

# Calculate Four Pillars of Destiny (BaZi)

`POST /chinese/bazi`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/chinese/bazi`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Compute the Four Pillars (八字 BaZi) for a birth date and time. Returns the Heavenly Stem and Earthly Branch for each pillar (year, month, day, hour), along with the Day Master — the core element of BaZi self-analysis.

**Heavenly Stems**: 10 stems cycling through 5 elements × 2 polarities.
**Earthly Branches**: 12 branches, each associated with a zodiac animal.
**Day Master (日主)**: The Day Stem's element represents the self.

**Note**: The Year and Month Pillars both roll over at Lì Chūn (立春, ~Feb 4), the traditional solar-term boundary — not at 1 January. A birth before Lì Chūn belongs to the previous sexagenary year. See metadata for the exact solar term used.

**Metering**: 1 unit per call.

## Query parameters

- `format` string: Response format: json (full) or llm (compact columnar).

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable
- `X-OpenEphemeris-API-Key` string, nullable
- `apikey` string, nullable

## Request body

- BaZiRequest: Request body for a BaZi (Four Pillars) calculation.
  - `day` integer, required: Birth day of month (1–31).
  - `day_boundary` 'zi_hour' | 'midnight': Day-pillar boundary convention. zi_hour rolls the day pillar at 23:00 (start of the Zi hour); midnight rolls it at 00:00.
  - `format` 'json' | 'llm': Response format: json | llm.
  - `hour` integer: Birth hour (0–23). Defaults to 12 (noon). Chinese hours (shí) are 2-hour blocks, so precision within a 2-hour window is sufficient.
  - `latitude` number, double: Birth latitude in decimal degrees (north positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.
  - `longitude` number, double: Birth longitude in decimal degrees (east positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.
  - `minute` integer: Birth minute (0–59). Defaults to 0, which reproduces the integer-hour behaviour exactly. Chinese hours (shí) are 2-hour blocks starting on odd hours, so a minute alone never moves the hour branch — it becomes load-bearing under true_solar_time, where the correction of up to ~±45 minutes is added to hour+minute/60 before the block and the 23:00 zi-hour tests are applied, and in the solar-term frame, where it shifts the birth instant by up to 59 minutes and can flip a Li Chun or Jié comparison for a birth within an hour of one.
  - `month` integer, required: Birth month (1–12).
  - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets.
    - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
    - `iana_name` string: IANA timezone name
    - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
    - `utc_offset` number: UTC offset in hours
  - `true_solar_time` boolean: When true, the birth wall clock is converted to local apparent (true) solar time before the pillars are derived: the longitude correction relative to the timezone's standard meridian plus the equation of time. The correction can move the day - and therefore the day pillar and, through it, the hour stem - as well as the hour branch. The year and month pillars are compared at the true birth INSTANT and are unaffected by the correction, which transforms a clock reading rather than moving the birth. Requires latitude and longitude.
  - `year` integer, required: Gregorian birth year.
  - `year_boundary` 'lichun' | 'cny': Year-pillar boundary convention. lichun rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year.

## Response `200`

Full Four Pillars with stems, branches, and Day Master.

- BaZiResponse: Full Four Pillars response.
  - `day` StemBranchPair, required: A Heavenly Stem + Earthly Branch pair (one pillar).
    - `branch` object, required
    - `stem` object, required
  - `day_master` object, required: The Day Master (日主): the Day Stem's element, representing the self in BaZi interpretation.
  - `hour` StemBranchPair, required: A Heavenly Stem + Earthly Branch pair (one pillar).
    - `branch` object, required
    - `stem` object, required
  - `metadata` object, required
  - `month` StemBranchPair, required: A Heavenly Stem + Earthly Branch pair (one pillar).
    - `branch` object, required
    - `stem` object, required
  - `success` boolean
  - `year` StemBranchPair, required: A Heavenly Stem + Earthly Branch pair (one pillar).
    - `branch` object, required
    - `stem` object, required

## Other responses

- `422`: Validation error (bad date, out-of-range values).

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)