Calculate endpoint — Four Pillars & the five-element distribution.

What it returns

Where /interpret adds an analysis layer (Ten Gods, Yongshin, Daeun), /calculate stays at the foundation: it converts a birthdate into the eight characters of a Saju chart and counts how the five elements are distributed across them. That makes it the right call when you only need the raw chart and the elemental balance — for example to drive a color theme, a personality summary, or your own downstream scoring.

• Four Pillars — year, month, day, and hour, each as a Heavenly Stem + Earthly Branch (with Hanja).
• Five-element distribution — an integer count for wood, fire, earth, metal, and water across the chart.
• Day Master — the stem of the Day Pillar, with its element and yin/yang polarity.
• Zodiac animal — derived from the Year Pillar branch.

Request

POST /api/v1/calculate takes a solar birthdate as year, month, day, hour, gender, plus an optional lang. Use hour: -1 when the birth time is unknown — the Hour Pillar comes back null and the element counts are computed from the remaining three pillars.

curl -X POST https://saju-api.pages.dev/api/v1/calculate \
  -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/calculate", {
  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.pillars);     // Four Pillars
console.log(data.elements);    // { wood, fire, earth, metal, water }
console.log(data.day_master);  // stem, element, polarity

import requests

res = requests.post(
    "https://saju-api.pages.dev/api/v1/calculate",
    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["pillars"])     # Four Pillars
print(data["elements"])    # {"wood":..,"fire":..,"earth":..,"metal":..,"water":..}
print(data["day_master"])  # stem, element, polarity

Request fields

Response fields

Response shape

{
  "input": { "year": 1990, "month": 5, "day": 15, "hour": 14, "gender": "M", "lang": "en" },
  "pillars": {
    "year":  { "stem": "...", "branch": "...", "stem_hanja": "...", "branch_hanja": "..." },
    "month": { "stem": "...", "branch": "...", "stem_hanja": "...", "branch_hanja": "..." },
    "day":   { "stem": "...", "branch": "...", "stem_hanja": "...", "branch_hanja": "..." },
    "hour":  { "stem": "...", "branch": "...", "stem_hanja": "...", "branch_hanja": "..." }
  },
  "elements": { "wood": 0, "fire": 2, "earth": 2, "metal": 3, "water": 1 },
  "day_master": { "stem": "...", "element": "metal", "polarity": "yang" },
  "zodiac": "horse",
  "tier": "free",
  "remaining": 98
}

Reading the element distribution

The elements object always sums to the number of pillars counted (eight characters for a full chart, six when the birth time is unknown). A count of 0 for an element means that element is absent from the chart — a common signal in Saju for an imbalance. Because the values are plain integers, you can drive your own UI from them directly:

const e = data.elements;                       // { wood, fire, earth, metal, water }
const total = e.wood + e.fire + e.earth + e.metal + e.water;
const dominant = Object.keys(e).reduce((a, b) => (e[b] > e[a] ? b : a));
const missing  = Object.keys(e).filter((k) => e[k] === 0);

// e.g. theme the chart by its dominant element, or flag missing ones
console.log(dominant);  // "metal"
console.log(missing);   // ["wood"]

Common use cases

• Four Pillars charts. Render the eight characters (stems + branches with Hanja) directly from pillars — no interpretation needed.
• Elemental balance visuals. Turn elements into a bar, radar, or donut chart, or map the dominant element to a color theme.
• Day Master features. Store day_master.stem once and reuse it to call the daily endpoint for a recurring fortune feature.
• LLM grounding. Feed the structured chart into a prompt as facts so an assistant describes it without inventing the Saju mechanics. For Ten Gods and Yongshin, step up to /interpret.

Errors

Related

• Developer quickstart — get a free key and call every endpoint.
• Interpret endpoint — Ten Gods, Yongshin & Daeun on top of the same chart.
• Birthdate → Four Pillars chart — a worked use case for this endpoint.
• OpenAPI 3.1 spec · Postman collection.