chinese

Calculate Four Pillars of Destiny (BaZi)

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.

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

Query parameters

formatstring

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

Headers

authorizationstring nullable
X-API-Keystring nullable
X-OpenEphemeris-API-Keystring nullable
apikeystring nullable

Request body

dayinteger 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.

hourinteger

Birth hour (0–23). Defaults to 12 (noon). Chinese hours (shí) are 2-hour blocks, so precision within a 2-hour window is sufficient.

latitudenumber 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.

longitudenumber 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.

minuteinteger

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.

monthinteger required

Birth month (1–12).

true_solar_timeboolean

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.

yearinteger 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.

Example request

{
  "day": 15,
  "hour": 8,
  "latitude": 31.2304,
  "longitude": 121.4737,
  "minute": 30,
  "month": 1,
  "timezone": {
    "iana_name": "America/New_York"
  },
  "year": 1990
}

Response

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

day_masterobject required

The Day Master (日主): the Day Stem's element, representing the self in BaZi interpretation.

metadataobject required
successboolean

Changes

No recorded changes to this operation across all 1 revision of this API.