Korean saju calendar API · for developers & AI agents
LLMs guess the pillars.
This API calculates them.
Send a birth time and get back the four pillars (사주팔자), luck periods and the full calculation basis. Solar terms come from a planetary ephemeris; clock time is resolved through Korea’s time-zone and DST history down to apparent solar time. The same input always gives the same answer — and every answer shows its work.
The clock says 09:30, but apparent solar time is 08:48:47 — the hour is 辰, not 巳.
Why
A saju calendar is a calculation, not a lookup
For one chart to be right, all of this has to be right. Language models get it plausibly wrong — and never say so.
Response
The answer, and the reasoning behind it
One response carries the result and how it was reached. Show it in your product or let an agent quote it — the basis is there to cite.
Four pillars
Year, month, day and hour in hangul and hanja, with sexagenary, stem and branch indices.
Luck periods
Direction, start age as an exact fraction, and the start and end instant of every period.
Ten gods · hidden stems
On request. Only approved rule-set versions are served.
Calculation basis
The Start-of-Spring and jie instants used, their error bounds, the day-pillar date and Julian day number.
Time resolution
UTC instant, applied offset and DST, longitude correction, equation of time, the calculation clock and the lunar date.
Provenance
Dataset, ephemeris hash, tzdb version, applied policy and a calculation fingerprint — reproducible later.
Verified
Checked against independent sources
Cross-checked with a reference implementation written separately from the engine, and with official external data.
Supported: Gregorian birth dates 1900-01-01 – 2100-12-31, time zone Asia/Seoul. All arithmetic is integer, so results are identical on any CPU architecture.
For agents
Built to be called by agents
Besides this page, there are entry points an agent can read mechanically.
Summary for agents
Endpoints, required input, an example and how to read the response, in one file. Full text at /llms-full.txt.
OpenAPI 3.1 contract
Types, constraints, examples and error codes for every field — ready to turn into tool definitions.
GET api.…/API root index
The API host root returns links to docs, contract and health as JSON. Every error uses the same JSON shape.
Same input, same answer
With the same provenance.dataset_id and policy the result does not change. Cache it, and cite it when you explain a chart.
No silent guessing
If boundary_status is not stable, show every entry of candidates to the user. Picking one is not the agent’s call.
Quickstart
Make your first call
Three inputs are required: local birth time, time zone and longitude. Everything else falls back to policy defaults, recorded in resolved_policy.
# Gregorian 1990-03-15 09:30, Seoul curl -X POST https://api.perpetual.smartlink.ai.kr/v1/charts \ -H "X-API-Key: $FOUR_PILLARS_KEY" \ -H "Content-Type: application/json" \ -d '{ "birth": { "calendar": "gregorian", "local_datetime": "1990-03-15T09:30:00", "timezone": "Asia/Seoul", "longitude": 126.978 } }'
{
"pillars": {
"year": { "hangul": "경오", "hanja": "庚午" },
"month": { "hangul": "기묘", "hanja": "己卯" },
"day": { "hangul": "기묘", "hanja": "己卯" },
"hour": { "hangul": "무진", "hanja": "戊辰" }
},
"uncertainty": {
"boundary_status": "stable",
"nearest_boundaries": [
{ "kind": "hour", "distance_seconds": 672.75 }
]
},
"provenance": {
"dataset_id": "kr-v3-2026c-de440s-0c26b6295d",
"calculation_fingerprint": "…"
}
}
| Endpoint | Description |
|---|---|
| POST/v1/charts | Pillars, luck periods, derived relations, uncertainty and basis. Gregorian (gregorian) or Korean lunar (korean_lunar, leap months included) input. |
| GET/v1/convert | Gregorian ↔ Korean lunar date conversion (leap months included) and the date's day cycle. ?calendar=korean_lunar&date=1985-08-15 |
| GET/v1/ganzhi | A date's day cycle (일진), the year and month pillars as it begins, and any solar-term change that day. ?date=2024-02-04 |
| GET/v1/policies | Approved policies, defaults, allowed options (clock basis, zi-hour handling, lunar meridian) and datasets. |
| GET/v1/solar-terms | The 24 solar-term instants of a year. ?year=YYYY |
| GET/v1/lunar-months | Months of a lunar year, leap months included. ?lunar_year=YYYY |
Options: clock basis civil · local_mean_solar · local_apparent_solar (default);
zi hour midnight (default) · zi_start_23 · split_zi.
Errors are {"code","message","request_id","details"}.
Access
Two ways in
Teams use an API key. AI agents will be able to pay per call.
X-API-Keyheader, per-key rate limits- For teams adding saju calculation to a product
- Birth data is never stored (
Cache-Control: no-store)
- No account — pay per call with x402 (USDC on Base)
- Agents pay and call on their own
- Requests that fail input validation are never charged