Build a daily fortune feature — Korean Saju, not sun-signs.

1Why Day Master beats sun-sign for a fortune feed

In Korean Saju, your daily reading hangs off your Day Master — the Heavenly Stem of your birth day, one of ten (갑/을/병/정/무/기/경/신/임/계, i.e. yin & yang of wood, fire, earth, metal, water). The daily endpoint scores how a given calendar day’s pillar interacts with each Day Master, so the result is a culturally grounded reading rather than a generic Western zodiac line.

• Ten buckets, not twelve generic ones — group every user by their Day Master once, then the whole feed is at most ten reads per day.
• Deterministic per (Day Master, date) — the same input always returns the same score, so it caches cleanly and is safe for widgets and push.
• Localized — advice_label comes back in any of 10 languages while advice_key stays stable for your own copy.

2Get a free key, then one GET per day

Keys are self-serve and free (100 requests/day, no card). Send your email to the key endpoint, store the key, and send it on every request as X-API-Key.

curl -X POST https://saju-api.pages.dev/api/v1/keys/create \
  -H "Content-Type: application/json" \
  -d '{ "email": "dev@yourcompany.io" }'

const res = await fetch("https://saju-api.pages.dev/api/v1/keys/create", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "dev@yourcompany.io" }),
});
const { api_key } = await res.json(); // sajuapi_free_...  shown once, store it

import requests

res = requests.post(
    "https://saju-api.pages.dev/api/v1/keys/create",
    json={"email": "dev@yourcompany.io"},
)
api_key = res.json()["api_key"]  # sajuapi_free_...  shown once, store it

Fetch today’s fortune for a Day Master

day_master is required — pass a Korean stem (갑 … 계) or an English alias (wood_yang, water_yin, …). date and lang are optional; date defaults to today.

curl "https://saju-api.pages.dev/api/v1/daily?day_master=wood_yang&date=2026-06-14&lang=en" \
  -H "X-API-Key: sajuapi_free_YOUR_KEY"

const params = new URLSearchParams({
  day_master: "wood_yang",
  date: "2026-06-14",
  lang: "en",
});
const res = await fetch(
  `https://saju-api.pages.dev/api/v1/daily?${params}`,
  { headers: { "X-API-Key": "sajuapi_free_YOUR_KEY" } },
);
const day = await res.json();
console.log(day.score);        // 0..100
console.log(day.advice_key);   // favor_action | favor_planning | rest_recover
console.log(day.advice_label); // localized, e.g. "Day to rest and recover"

import requests

res = requests.get(
    "https://saju-api.pages.dev/api/v1/daily",
    headers={"X-API-Key": "sajuapi_free_YOUR_KEY"},
    params={"day_master": "wood_yang", "date": "2026-06-14", "lang": "en"},
)
day = res.json()
print(day["score"])        # 0..100
print(day["advice_key"])   # favor_action | favor_planning | rest_recover
print(day["advice_label"]) # localized label

Example response

{
  "date":       "2026-06-14",
  "day_pillar": { "stem": "...", "branch": "...", "stem_hanja": "...", "branch_hanja": "..." },
  "day_master": "...",
  "score":      31,
  "advice_key": "rest_recover",
  "advice_label": "Day to rest and recover",
  "lang":       "en",
  "tier":       "free",
  "remaining":  99
}

The three possible advice_key values let you branch on intent without parsing text:

3Cache once, serve everyone

Because the reading depends only on the Day Master and the date, the daily response ships with a CDN-friendly cache header:

Cache-Control: s-maxage=3600, stale-while-revalidate=86400

A shared cache (Cloudflare, Fastly, a Redis key, or your edge runtime) can store one entry per (Day Master, date) and reuse it for every user who shares that Day Master. With only ten Day Masters, a whole day of fortunes for your entire user base is at most ten upstream calls — the rest are cache hits.

Warm all ten at midnight (Node, pseudo-cron)

const DAY_MASTERS = [
  "wood_yang", "wood_yin", "fire_yang", "fire_yin", "earth_yang",
  "earth_yin", "metal_yang", "metal_yin", "water_yang", "water_yin",
];

async function warmDailyCache(date, lang = "en") {
  const today = {};
  for (const dm of DAY_MASTERS) {
    const params = new URLSearchParams({ day_master: dm, date, lang });
    const res = await fetch(
      `https://saju-api.pages.dev/api/v1/daily?${params}`,
      { headers: { "X-API-Key": process.env.SAJU_API_KEY } },
    );
    today[dm] = await res.json(); // store in your cache / DB keyed by (dm, date)
  }
  return today; // ten fortunes; serve to every user from here
}

4Wire it to push notifications & widgets

Once the ten fortunes are cached, sending a morning push is a lookup, not an API call. Map each user to their stored Day Master, read the cached entry, and format with advice_key:

// after warmDailyCache(date) has populated `today`
function buildPush(user, today) {
  const f = today[user.dayMaster];               // cached, no network
  const emojiByKey = {
    favor_action:   "⚡",                   // map to your own icon set
    favor_planning: "📝",
    rest_recover:   "🌙",
  };
  return {
    title: `Today's fortune · ${f.score}/100`,
    body:  `${emojiByKey[f.advice_key] || ""} ${f.advice_label}`,
    data:  { advice_key: f.advice_key, date: f.date },
  };
}

• Home-screen widget — render the score as a ring or bar and the advice_label as the caption.
• Push notification — short by design: one number and one line, branch on advice_key for tone and icon.
• Streak / engagement loop — a fresh, deterministic reading every day gives users a reason to open the app.

5Languages, errors & limits

Pass lang to localize advice_label. Supported: ko, en, ja, zh, es, pt-br, vi, id, hi, th. The stable advice_key lets you keep your own copy in any language you like.

Check remaining quota any time with GET /api/v1/usage (send your key in the X-API-Key header). Every successful response also includes a remaining field.

Next steps

• Developer quickstart — get a key and call calculate to find each user’s Day Master.
• Interpret endpoint — Ten Gods, Yongshin, and Daeun for a richer profile screen.
• Compatibility API — a 0–100 two-person 궁합 score.
• OpenAPI 3.1 spec & Postman collection — full schemas for every endpoint.

Saju (사주팔자, Korean Four Pillars of Destiny) is a traditional cultural and fortune-telling system. Output from this API, including the daily score and advice, is provided for entertainment and reflection only and must not be presented as a prediction or as financial, medical, legal, or professional advice.