Saju API › Zi Wei Dou Shu API

Zi Wei Dou Shu API

Send a birth date and time and get a Zi Wei Dou Shu (Purple Star) chart as JSON: the 12 palaces, the 14 major stars and the minor stars (with brightness and birth-year transformations), the Five Elements bureau, the positions of the Life and Body palaces, and the decade and annual periods for a reference date. Zi Wei Dou Shu is a Chinese astrology system that places stars in 12 palaces, each standing for an area of life. The product is called "Zi Wei Dou Shu chart". The same input always gives the same result.

Get Started guide Playground Pricing

What it returns

• 12 palaces — the palace name, Heavenly Stem, Earthly Branch, decade-period ages and the stars in that palace (palaces)
• Stars — the 14 major stars and the minor stars, their brightness and birth-year transformations (majorStars·minorStars)
• Birth-year transformations — Hua Lu, Hua Quan, Hua Ke and Hua Ji (the four transformations: wealth, power, fame and obstacle) and the palace each transformed star sits in (mutagens)
• Decade and annual periods — the decade period and the annual palace for the reference date (currentDecadal·yearly)
• Rule keys — a list of facts that hold in the chart, written as Zi Wei Dou Shu rule key strings (features)

Adding reading paragraphs

Send readings: true to add reading paragraphs for the major-star combination of the Life palace, 7 topics, and the major stars of the Wealth, Career, Spouse and Health palaces. This costs extra; the amount is in the reference.

Without a birth time

A Zi Wei Dou Shu chart cannot be drawn without a birth time, so leaving out hour returns 400 birth_time_required. It is an error response, so nothing is deducted.

Request example

{
  "year": 1990, "month": 5, "day": 15, "hour": 14, "minute": 30,
  "gender": "female", "referenceDate": "2026-10-08", "lang": "ko"
}

Authentication uses the X-Partner-Api-Key header, and the base URL is https://api.hrum.ai/api/v1/partners/v1. Python and JavaScript examples and error handling are in the Get Started guide.

Response example (excerpt)

{
  "success": true,
  "data": {
    "engineVersion": 1,
    "lang": "ko",
    "referenceDate": "2026-10-08",
    "clock": {
      "inputSolarDate": "1990-05-15", "inputTime": "14:30",
      "correctedSolarDate": "1990-05-15", "correctedTime": "14:30",
      "correctionMinutes": 0, "dstApplied": false, "basis": null,
      "hourBranch": { "key": "wei", "label": "미" }
    },
    "chart": {
      "engine": { "name": "iztro", "version": "2.6.1", "config": { ... } },
      "solarDate": "1990-05-15",
      "lunarDate": { "year": 1990, "month": 4, "day": 21, "isLeapMonth": false },
      "yearGanzhi": "경오",
      "yearBasisNote": null,
      "fiveElementsClass": { "key": "earth5", "label": "토오국" },
      "soulPalaceBranch": { "key": "xu", "label": "술" },
      "bodyPalaceBranch": { "key": "zi", "label": "자" },
      …

The start of the response to the request above. The response with the 12 palaces, transformations and rule keys, and the field descriptions are in the reference.

Pricing

The Zi Wei Dou Shu chart costs ₩50 per call (excl. VAT; ₩55 incl. VAT). Only successful calls are deducted from prepaid credits; 4xx and 5xx error responses are not charged.

Store a result once you have it, and reuse it. Sending the same request again is charged again. The same birth date and time with the same options always gives the same result, so save the first response in your database (for example, keyed by a hash of the request body) and use the saved value from then on at no cost. For results that change by date, such as a daily fortune, include the date in the key and reuse the result for that day only.

Full pricing

Full reference

The full parameter table, response field descriptions and error codes are in the reference: Zi Wei Dou Shu chart API reference. Other Saju products are listed under All Saju APIs.

Contact: contact@float.do · Operated by FLOAT Co., Ltd.