BaZi Luck Pillars (Da Yun)

ISO 8601 alternative to year/month/day/hour. Its calendar components are read as the naive LOCAL wall clock; the UTC offset the string spells is not used to convert them. Because of that, a datetime carrying an offset (Z or +/-HH:MM) together with a timezone (or latitude+longitude, from which a zone is resolved) states the birth zone twice: if the two disagree the request is rejected 422 rather than shifted twice. To use a zone, send year, month, day and hour as the local wall clock alongside timezone. Its MINUTES are also discarded: only the hour is read, so "1990-02-03T22:30:00" is computed as 22:00. Send hour and minute alongside year/month/day to express a sub-hour birth time.

Day-pillar boundary convention. zi_hour rolls the day pillar at 23:00 (start of the Zi hour); midnight rolls it at 00:00.

Response format: json | llm.

Required: determines direction (forward/backward) of Da Yun progression.

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.

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.

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.

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.

Birth year (Gregorian)

Year-pillar boundary convention. lichun rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year.