How to Cast a Zi Wei Dou Shu Chart with the API

POST /chinese/ziwei returns the natal chart of Zi Wei Dou Shu (Purple Star Astrology) for a birth. It was added in API 4.3.0. The response holds the twelve palaces with their stems and roles, the Life and Body palaces, the five-element bureau, the 14 major and 14 minor stars with brightness, the four transformations of the year stem, and the ten-year cycles.

It returns placements and the conventions used to produce them. It does not return interpretation text.

---

When to use it

Use it when you have a birth date, a birth hour and a gender, and you want the Zi Wei chart as data: to draw the twelve-palace grid, to store the placements, or to hand them to your own reading layer.

The lunisolar date is computed from the engine's own new moons and solar terms, not from a lookup table. The supported birth years are 1551 to 2648.

The request

curl -X POST https://api.openephemeris.com/chinese/ziwei \
  -H "X-API-Key: $OPENEPHEMERIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "year": 1987,
    "month": 7,
    "day": 15,
    "hour": 9,
    "minute": 1,
    "gender": "female"
  }'

Fields:

• year, month, day (required): the Gregorian birth date. year is 1551 to 2648.
• hour (required): the birth hour, 0 to 23, on the local wall clock. Nothing defaults to noon. A missing hour is a 422.
• gender (required): male or female. It sets the direction of the ten-year cycles. A missing or other value is a 422.
• minute (optional, default 0): 0 to 59. It is read only when year_boundary is lichun. With the default calendar, the hour decides the chart.
• leap_month_rule (optional): split_mid (default), previous or next. It decides which month number a birth inside a leap month uses.
• day_boundary (optional): zi_hour (default) or midnight.
• year_boundary (optional): cny (default) or lichun.
• transformation_overrides (optional): replaces the four transformations of a year stem, for example {"geng": ["tai_yang", "wu_qu", "tai_yin", "tian_tong"]}. Each value must be exactly four star ids in the order lu, quan, ke, ji.
• format (optional): json (default) or llm. With llm the palace objects move into metadata as fixed-width rows.

The response

This is a real response to the request above, trimmed: two of the twelve palaces are shown, and the star lists in them are shortened.

{
  "success": true,
  "chart": {
    "algorithm_version": "ziwei-1.0.0",
    "conventions": {
      "age_reckoning": "nominal",
      "brightness_table": "common-v1",
      "day_boundary": "zi_hour",
      "four_transformations_table": "common",
      "leap_month_rule": "split_mid",
      "overridden_stems": [],
      "year_boundary": "cny",
      "year_boundary_frame": "civil_date"
    },
    "lunar": {
      "birth": { "year": 1987, "month": 6, "day": 20, "leap": false, "month_days": 30 },
      "effective": { "year": 1987, "month": 6, "day": 20, "leap": false, "month_days": 30 },
      "effective_civil": [1987, 7, 15],
      "late_zi_rolled": false,
      "leap_month_adjusted": false,
      "month_for_palaces": 6
    },
    "year_stem": "ding",
    "year_branch": "mao",
    "hour_branch": "si",
    "life": { "branch": "yin", "stem": "ren" },
    "body": { "branch": "zi", "role": "spouse" },
    "bureau": { "id": "metal_4", "number": 4, "nayin": "金箔金" },
    "zi_wei_branch": "wu",
    "tian_fu_branch": "xu",
    "four_transformations": {
      "lu": "tai_yin",
      "quan": "tian_tong",
      "ke": "tian_ji",
      "ji": "ju_men"
    },
    "decades": { "direction": "clockwise", "start_age": 4, "rule": "yin_year_female" },
    "palaces": [
      {
        "branch": "yin",
        "stem": "ren",
        "role": "life",
        "is_body": false,
        "is_origin": false,
        "decade_start_age": 4,
        "decade_end_age": 13,
        "major": [
          { "id": "wu_qu", "brightness": "de" },
          { "id": "tian_xiang", "brightness": "miao" }
        ],
        "minor": [{ "id": "huo_xing", "brightness": "miao" }]
      },
      {
        "branch": "si",
        "stem": "yi",
        "role": "property",
        "is_body": false,
        "is_origin": false,
        "decade_start_age": 34,
        "decade_end_age": 43,
        "major": [{ "id": "tian_ji", "brightness": "ping", "transformation": "ke" }],
        "minor": [
          { "id": "you_bi" },
          { "id": "wen_chang", "brightness": "miao" },
          { "id": "tian_ma" },
          { "id": "tuo_luo", "brightness": "xian" }
        ]
      }
    ],
    "warnings": []
  },
  "metadata": {
    "algorithm_version": "ziwei-1.0.0",
    "calendar": "lunisolar from the engine's new moons and solar terms, Beijing time"
  }
}

How to read it:

• palaces always has twelve entries, in order from Yin (index 0) to Chou (index 11). role names the palace (life, parents, fortune, and so on). is_body marks the palace the Body sits in. is_origin marks the origin palace.
• decade_start_age and decade_end_age are nominal ages. conventions.age_reckoning says so.
• A star carries brightness (miao, wang, de, li, ping, bu or xian) only when the table has a grade for that star in that palace. A star carries transformation (lu, quan, ke or ji) when the year stem transforms it. four_transformations lists the four stars for the year stem.
• lunar.birth is the lunar date of the civil date you sent. lunar.effective is the lunar date the chart used. They differ after the late-Zi roll, described below.

Cost

2 credits per call, on every plan including the free Explorer tier. The first call for a year the server has not computed can take a few tenths of a second longer than later calls for the same year.

Gotchas

The date and time are the local wall clock, already resolved. This endpoint has no timezone field. You apply the zone, daylight saving time and any true-solar-time correction before you send the hour, and the endpoint reads your numbers as stated. A wrong zone does not raise an error. It returns a different chart that looks fine. For how to resolve place, zone and instant in the right order, see A Timestamp Is Not a Moment.

Hour and gender are required, never guessed. The chart cannot be cast without the birth hour. If you only have a date, ask the user for the hour rather than sending a placeholder.

Late Zi rolls the whole lunar date. With the default day_boundary of zi_hour, a birth from 23:00 to 23:59 belongs to the next day, and the lunar year, month, day and leap flag are all taken from that next day. Check lunar.late_zi_rolled and lunar.effective_civil. With midnight, the day changes at 00:00 and 23:00 to 23:59 is the Zi hour of the same day.

The schools disagree, so each choice is an option. The leap-month rule, the day boundary, the year boundary and a few transformation stems differ between schools. Whatever you send or leave at the default is echoed in chart.conventions, so a stored chart always says how it was made. If you compare output with another Zi Wei tool, compare the conventions first.

The year boundary default is cny. The year changes at Chinese New Year by default. This differs from the default on the BaZi endpoints. With lichun, the year changes at the Lichun solar term, the wall clock is read as Beijing time (UTC+8), and conventions.year_boundary_frame says beijing_wall_clock.

Read warnings. The codes are lunar_boundary_within_minutes, late_zi_rolled_lunar_boundary and leap_month_birth. The first two mean the birth is within minutes of a lunar month boundary, or the late-Zi roll crossed one, so the day numbering may differ from a published table by one day.

Brightness comes from one table. brightness_table is common-v1, the only table. It was transcribed from the open-source iztro 2.6.3 package and has not been cross-checked against a second source. Treat brightness as a lookup from that table, not as a validated ranking.

What is not in this version. The Zhong Zhou school rules, adjective stars, and yearly or monthly overlays.