---
title: "BaZi Luck Pillars (Da Yun)"
method: POST
path: "/chinese/bazi/luck-pillars"
tags: ["chinese"]
---

# BaZi Luck Pillars (Da Yun)

`POST /chinese/bazi/luck-pillars`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/chinese/bazi/luck-pillars`
- 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`

Calculate the eight 10-year Da Yun (大运) luck pillars for a BaZi chart. Starting age is computed from the nearest solar term (Jié) boundary — 3 days from birth = 1 year of starting age (classical Zi Ping rule).

Requires gender to determine whether pillars progress forward or backward through the sexagenary cycle.

**Metering**: 3 units per call.

## Request body

- BaZiLuckPillarsRequest: Request for Da Yun (大运) luck pillar calculation. Requires either year/month/day or datetime, plus gender.
  - `datetime` string, date-time: 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` integer
  - `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.
  - `gender` 'male' | 'female', required: Required: determines direction (forward/backward) of Da Yun progression.
  - `hour` integer
  - `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
  - `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: Birth year (Gregorian)
  - `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`

Eight Da Yun luck pillars with starting age and direction.

- BaZiLuckPillarsResponse
  - `calculation_metadata` object: Optional calculation provenance metadata (timing, engine flags, ayanamsa, etc.). Free-form; present when the handler attaches it.
  - `direction` 'forward' | 'backward', required
  - `direction_reason` string, required
  - `pillars` BaZiLuckPillar[], required
    - `branch` string, required
    - `branch_chinese` string, required
    - `element` 'Wood' | 'Fire' | 'Earth' | 'Metal' | 'Water', required
    - `end_age` number, double, required
    - `number` integer, required: Ordinal position (1 = first luck pillar)
    - `start_age` number, double, required
    - `stem` string, required
    - `stem_chinese` string, required
  - `starting_age` number, double, required
  - `success` boolean

## Other responses

- `422`: Validation error.

---

[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)