Interpret endpoint — Ten Gods, Yongshin & Daeun in one call.

Where /calculate gives you the raw Four Pillars, /interpret adds the analysis layer of Korean Saju (사주 / Four Pillars, the Korean reading of Bazi): Ten Gods (십신), 12 Life Stages, hidden stems, branch interactions, the Yongshin (useful element), and Daeun — the 10-year luck cycles. One POST, structured JSON, 10 languages.

Request

POST /api/v1/interpret takes the same body as /calculate: year, month, day, hour, gender, plus an optional lang. Use hour: -1 when the birth time is unknown.

curl -X POST https://saju-api.pages.dev/api/v1/interpret \
  -H "X-API-Key: sajuapi_free_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "year":  1990,
    "month": 5,
    "day":   15,
    "hour":  14,
    "gender":"M",
    "lang":  "en"
  }'
const res = await fetch("https://saju-api.pages.dev/api/v1/interpret", {
  method: "POST",
  headers: {
    "X-API-Key": "sajuapi_free_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    year: 1990, month: 5, day: 15, hour: 14, gender: "M", lang: "en",
  }),
});
const data = await res.json();
console.log(data.ten_gods);   // Ten Gods per pillar
console.log(data.yongshin);   // useful element
console.log(data.daeun);      // 10-year luck cycles
import requests

res = requests.post(
    "https://saju-api.pages.dev/api/v1/interpret",
    headers={"X-API-Key": "sajuapi_free_YOUR_KEY"},
    json={"year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "M", "lang": "en"},
)
data = res.json()
print(data["ten_gods"])   # Ten Gods per pillar
print(data["yongshin"])   # useful element
print(data["daeun"])      # 10-year luck cycles

Response fields

FieldWhat it is
pillarsThe Four Pillars (year / month / day / hour), each with stem, branch, and Hanja.
ten_godsThe Ten Gods (십신 / Sipshin) — the relationship of each stem to the Day Master (e.g. wealth, officer, resource, peer).
life_stagesThe 12 Life Stages (12운성) for the chart — the strength phase of each pillar.
hidden_stemsHidden stems (지장간) concealed inside each Earthly Branch.
interactionsBranch interactions: harmonies (합), clashes (충), and related combinations.
yongshinYongshin (용신) — the most useful / balancing element for the chart.
daeunDaeun (대운) — the sequence of 10-year luck cycles (the "luck pillars").
summaryLocalized human-readable strings for the pillars and Yongshin, in the requested lang.
remainingRequests left in your daily quota.

Response shape

{
  "input":   { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "M", "lang": "en" },
  "pillars":      { "year": { ... }, "month": { ... }, "day": { ... }, "hour": { ... } },
  "ten_gods":     { ... },
  "life_stages":  { ... },
  "hidden_stems": { ... },
  "interactions": { ... },
  "yongshin":     { ... },
  "daeun":        [ ... ],
  "summary":      { "lang": "en", "pillars": { ... }, "yongshin": "..." },
  "tier":         "free",
  "remaining":    97
}
Field presence is stable; the inner detail of each block reflects the underlying Saju engine. Treat blocks defensively (check for a key before reading nested values) so your client keeps working as the engine adds depth.

Common use cases

Errors

StatusMeaning
400invalid_input with a reason (e.g. year_out_of_range, gender_must_be_M_or_F, unsupported_lang). Year range is 1920–2050.
401Missing or malformed X-API-Key.
405Use POST for this endpoint.
429Daily quota for your tier exceeded.

Related

Get a free key Overview