Saju Compatibility API — a 0–100 match score from two birthdates.

What you send and get back

Post two people (person_a and person_b), each with a solar birthdate. Use hour: -1 when the birth time is unknown. The response is a flat JSON object: a top-level score, a breakdown, and a small summary of each person.

Call it

Send your free-tier key in the X-API-Key header. Get a key in the quickstart if you do not have one yet.

curl -X POST https://saju-api.pages.dev/api/v1/compatibility \
  -H "X-API-Key: sajuapi_free_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "person_a": { "year": 1990, "month": 5,  "day": 15, "hour": 14, "gender": "M" },
    "person_b": { "year": 1992, "month": 11, "day": 3,  "hour": 9,  "gender": "F" },
    "lang": "en"
  }'

const res = await fetch("https://saju-api.pages.dev/api/v1/compatibility", {
  method: "POST",
  headers: {
    "X-API-Key": "sajuapi_free_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    person_a: { year: 1990, month: 5,  day: 15, hour: 14, gender: "M" },
    person_b: { year: 1992, month: 11, day: 3,  hour: 9,  gender: "F" },
    lang: "en",
  }),
});
const data = await res.json();
console.log(data.score);              // 0-100
console.log(data.breakdown);          // { element_balance, day_master_relation, ... }

import requests

res = requests.post(
    "https://saju-api.pages.dev/api/v1/compatibility",
    headers={"X-API-Key": "sajuapi_free_YOUR_KEY"},
    json={
        "person_a": {"year": 1990, "month": 5,  "day": 15, "hour": 14, "gender": "M"},
        "person_b": {"year": 1992, "month": 11, "day": 3,  "hour": 9,  "gender": "F"},
        "lang": "en",
    },
)
data = res.json()
print(data["score"])       # 0-100
print(data["breakdown"])   # element_balance, day_master_relation, branch_harmony, branch_clash

Example response

{
  "score": 78,
  "breakdown": {
    "element_balance":     22,
    "day_master_relation": 30,
    "branch_harmony":      25,
    "branch_clash":         0
  },
  "person_a": { "day_master": "...", "day_master_element": "metal", "zodiac": "horse" },
  "person_b": { "day_master": "...", "day_master_element": "water", "zodiac": "monkey" },
  "tier":      "free",
  "remaining": 98
}

Designing the match screen

A few patterns that work well when you surface this in product:

• Score ring + one line. Render score as a 0–100 ring and pick a copy line from the dominant breakdown part (e.g. high day_master_relation → "your core energies generate each other").
• Element bars. Show each person's day_master_element and a five-bar element chart — the keys are English (wood / fire / earth / metal / water) so charting is trivial.
• Localize the copy, not the math. Pass lang to get human-readable strings in 10 languages while the numeric score stays identical across locales.
• Cache by pair. The score is deterministic for a given pair of birthdates, so you can cache it keyed on both birthdates and avoid repeat calls.

Errors

Next steps

• Developer quickstart — get a free key and call every endpoint.
• Interpret endpoint — Ten Gods, Yongshin, and Daeun (luck cycles) for a single chart.
• OpenAPI 3.1 spec · Postman collection.