chinese

BaZi Element Balance (Wu Xing)

Calculate the weighted Wu Xing (五行) element balance across all four pillars of a BaZi chart, including hidden stems within the earthly branches.

Returns percentage scores for each of the five elements, Day Master strength (strong/weak/neutral), and the recommended Yong Shen (用神) favourable element.

Metering: 3 units per call.

post/chinese/bazi/element-balance

Request

  • Base URL: https://api.openephemeris.com
  • URL: https://api.openephemeris.com/chinese/bazi/element-balance
  • 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

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

Five-element scores, Day Master strength, and Yong Shen.

calculation_metadataobject

Optional calculation provenance metadata (timing, engine flags, ayanamsa, etc.). Free-form; present when the handler attaches it.

day_master_elementstring required
day_master_strength'strong' | 'weak' | 'neutral' required
successboolean
total_scorenumber required
yong_shen_elementstring required

Recommended favourable element (用神 Yòng Shén).

Changes

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