Name: Saju API: Korean Four Pillars, BaZi, Compatibility & Fortune
Brand: kunstudio
SKU: api-kunstudio-saju-api
Availability: InStock
Author: API Market

덕구네

# Saju API — Korean Four Pillars, BaZi & Compatibility

## Overview
The Saju API provides a robust and benchmark-verified calculation engine for Korean **Saju (사주팔자, Four Pillars of Destiny)** and Chinese **BaZi** astrology. This powerful REST API allows developers to convert any solar (Gregorian) birthdate into a comprehensive astrological chart, including the four pillars (year, month, day, hour), five-element distribution, Ten Gods (십신), Yongshin (용신), Daeun (대운 luck pillars), two-person compatibility scores, and daily fortune snapshots. Results are available in 10 languages, making it ideal for global applications.

Built with precision, the engine is rigorously benchmark-verified against classical 만세력 (Ten-Thousand-Year Calendar) standards, accurately calculating solar-term (절기) month boundaries to ensure traditional and professional Saju reference matches.

## Features
*   **Four Pillars & Five Elements:** Accurately calculate year, month, day, and hour pillars (Heavenly Stem + Earthly Branch), along with the five-element distribution.
*   **Full Interpretation:** Get detailed interpretations including Ten Gods (십신), hidden stems, life stages, interactions, Yongshin (용신 / useful god), Daeun (대운 / luck pillars), and localized summaries.
*   **Compatibility Scoring (궁합):** Receive a precise 0-100 compatibility score between two individuals, complete with a breakdown of influencing factors.
*   **Daily Fortune Snapshot:** Obtain a daily fortune score (0-100) and personalized advice for a given Day Master and date.
*   **Multilingual Support:** Access interpretations and summaries in 10 languages: Korean (ko), English (en), Japanese (ja), Chinese (zh), Spanish (es), Brazilian Portuguese (pt-br), Vietnamese (vi), Indonesian (id), Hindi (hi), and Thai (th).
*   **Benchmark-Verified Accuracy:** Ensures traditional solar-term (절기) month boundaries are respected for highly accurate pillar calculations.
*   **Deterministic Results:** Provides consistent outputs for the same inputs, facilitating easy caching and testing.
*   **Battle-Tested Engine:** Leverages the same reliable engine found in the live consumer Saju app, 天命堂 (Cheonmyeongdang).

## Use Cases
*   **Astrology & Horoscope Applications:** Develop engaging apps that provide personalized Saju readings, daily horoscopes, or in-depth individual interpretations. Enhance user experience with culturally rich astrological insights.
*   **Dating & Relationship Platforms:** Integrate advanced compatibility matching features based on traditional Saju/BaZi principles. Offer users deeper insights into potential relationships, fostering more meaningful connections.
*   **Wellness & Lifestyle Apps:** Provide users with personalized daily guidance, self-discovery tools, and culturally relevant insights, particularly in Asian markets, to support their overall well-being.
*   **AI Chatbots & Virtual Assistants:** Equip AI models with Saju/BaZi knowledge to offer personality features, respond to user queries about destiny, or provide cultural divination as part of interactive conversational experiences.
*   **Gaming & Entertainment:** Incorporate Saju/BaZi elements into game narratives, character development, quest generation, or as an in-game fortune-telling mechanism to create unique and immersive experiences.


## API Documentation

### Base URL
All API requests should be made to:
`https://prod.api.market/api/v1/kunstudio/saju-api`

### Authentication
Authentication is handled via an API key provided by API.market. Include your API key in the request header:

```
x-api-market-key: YOUR_API_MARKET_KEY
```

This API key is used for billing and metering your usage through API.market.



### Endpoints

#### Common Request Fields (BirthRequest)
Many endpoints share a common structure for birthdate information:

| Field    | Type    | Required | Range / Values | Description |
|----------|---------|----------|----------------|-------------|
| `year`   | integer | yes      | 1920–2050      | Solar (Gregorian) birth year |
| `month`  | integer | yes      | 1–12           | Birth month |
| `day`    | integer | yes      | 1–31           | Birth day |
| `hour`   | integer | yes      | -1 to 23       | Birth hour, 24h clock. Use `-1` if the hour is unknown |
| `gender` | string  | yes      | `M` or `F`     | Affects Daeun (luck-pillar) direction |
| `lang`   | string  | no       | ko, en, ja, zh, es, pt-br, vi, id, hi, th | Output language (default `ko`) |

---

### 1. POST /api/v1/calculate — Four Pillars

Compute the Four Pillars from a solar birthdate. Returns the year/month/day/hour pillars (heavenly stem + earthly branch, with hanja), the five-element distribution, the Day Master, and the zodiac animal.

**Request**

```bash
curl -X POST "https://prod.api.market/api/v1/kunstudio/saju-api/api/v1/calculate" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{"year":1990,"month":5,"day":15,"hour":9,"gender":"M","lang":"en"}'
```

**Response** `200 OK`

```json
{
  "input": {"year":1990,"month":5,"day":15,"hour":9,"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":3,"earth":1,"metal":4,"water":0},
  "day_master": {"stem":"경","element":"metal","polarity":"yang"},
  "zodiac": "horse",
  "tier": "free",
  "remaining": 99
}
```

---

### 2. POST /api/v1/interpret — Full Interpretation

Full Saju interpretation: the Four Pillars plus Ten Gods (십신), hidden stems, life stages, interactions, Yongshin (용신 / useful god), Daeun (대운 / luck pillars), and human-readable summaries in the requested language.

**Request**

```bash
curl -X POST "https://prod.api.market/api/v1/kunstudio/saju-api/api/v1/interpret" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{"year":1990,"month":5,"day":15,"hour":9,"gender":"M","lang":"en"}'
```

**Response** `200 OK` (abridged)

```json
{
  "input": {"year":1990,"month":5,"day":15,"hour":9,"gender":"M","lang":"en"},
  "pillars": {
    "일주": {"간지":"경진","한자":"庚辰","천간":"경","지지":"진",
             "천간_오행":"금","지지_오행":"토","천간_음양":"양"},
    "summary": "경오 신사 경진 신사",
    "summary_한자": "庚午 辛巳 庚辰 辛巳"
  },
  "ten_gods": [
    {"위치":"년주","천간":{"글자":"경","십신":"비견"},"지지":{"글자":"오","십신":"정관"}},
    {"위치":"월주","천간":{"글자":"신","십신":"겁재"},"지지":{"글자":"사","십신":"편관"}}
  ],
  "yongshin": {
    "strength": "strong",
    "strength_label": "Strong Day Master",
    "useful_element": "water",
    "useful_element_label": "Water",
    "favored_element": "wood",
    "favored_element_label": "Wood",
    "avoid_element": "metal",
    "avoid_element_label": "Metal"
  },
  "summary": {
    "lang": "en",
    "pillars": [
      {"position": "year", "position_label": "Year Pillar", "stem_god": "Peer (Bi Jian) — independent, self-driven, values fairness", "branch_god": "Officer (Zheng Guan) — disciplined, responsible, seeks recognition"},
      {"position": "month", "position_label": "Month Pillar", "stem_god": "Rob Wealth (Jie Cai) — competitive, resourceful, seeks cooperation", "branch_god": "Seven Killings (Qi Sha) — challenging, determined, leadership potential"}
    ]
  },
  "tier": "free",
  "remaining": 99
}
```

The full response additionally includes `yongshin`, `daeun` (luck-pillar timeline), hidden stems, interactions, shinsal (special stars), and more localized summary text.

---

### 3. POST /api/v1/compatibility — Compatibility (궁합)

Score two-person compatibility (궁합) from 0–100 based on both people's Saju. Returns the overall score, a breakdown (element balance, Day Master relation, branch harmony, branch clash), plus each person's Day Master and zodiac.

**Request**

```bash
curl -X POST "https://prod.api.market/api/v1/kunstudio/saju-api/api/v1/compatibility" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
        "person_a": {"year":1990,"month":5,"day":15,"hour":9,"gender":"M"},
        "person_b": {"year":1992,"month":8,"day":3,"hour":14,"gender":"F"},
        "lang": "en"
      }'
```

**Response** `200 OK`

```json
{
  "score": 60,
  "breakdown": {
    "element_balance": 25,
    "day_master_relation": 15,
    "branch_harmony": 0,
    "branch_clash": 0
  },
  "person_a": {"day_master":"경","day_master_element":"metal","zodiac":"말"},
  "person_b": {"day_master":"신","day_master_element":"metal","zodiac":"원숭이"},
  "tier": "free",
  "remaining": 99
}
```

---

### 4. GET /api/v1/daily — Daily Fortune Snapshot

Daily fortune snapshot (0–100 score + advice) for a given Day Master and date. Provide the Day Master either as a Korean stem character (`갑, 을, 병, 정, 무, 기, 경, 신, 임, 계`) or an English alias (`wood_yang`, `water_yin`, ...). The Day Master comes from a prior `/calculate` or `/interpret` call (`day_master.stem`).

**Query parameters**

| Param        | Required | Description |
|--------------|----------|-------------|
| `day_master` | yes      | Korean stem (갑..계) or English alias |
| `date`       | no       | Target date `YYYY-MM-DD`. Defaults to today (UTC) |
| `lang`       | no       | Output language (default `ko`) |

**Request**

```bash
curl "https://prod.api.market/api/v1/kunstudio/saju-api/api/v1/daily?day_master=%EA%B0%91&date=2026-07-07&lang=en" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

**Response** `200 OK`

```json
{
  "date": "2026-07-07",
  "day_pillar": {"stem":"임","branch":"오","stem_hanja":"壬","branch_hanja":"午"},
  "day_master": "갑",
  "score": 36,
  "advice_key": "rest_recover",
  "advice_label": "Day to rest and recover",
  "lang": "en",
  "tier": "free",
  "remaining": 99
}
```

---

## Status Codes
The Saju API uses standard HTTP status codes to indicate the success or failure of an API request.

*   **`200 OK`**: The request was successful, and the response body contains the requested data.
*   **`400 Bad Request`**: The request was malformed or contained invalid input parameters. This often includes missing required fields or values outside the specified range. The response body will contain an `error` object with more details.
    *   Example: `{"error":"invalid_request", "reason":"year_out_of_range"}`
*   **`401 Unauthorized`**: Your API key is missing or invalid. Ensure the `x-api-market-key` header is correctly provided with a valid key.
    *   Example: `{"error":"invalid_api_key"}`
*   **`403 Forbidden`**: Valid API key but insufficient permissions for the requested operation (less common for this API, typically for tier-specific features).
*   **`404 Not Found`**: The requested resource could not be found. This usually indicates an incorrect endpoint URL.
*   **`429 Too Many Requests`**: You have exceeded your daily API request quota or the rate limit for your current tier. Check the `remaining` field in successful responses to monitor your usage.
    *   Example: `{"error":"rate_limited"}`
*   **`500 Internal Server Error`**: An unexpected error occurred on the server. This indicates a problem on the API's side.
*   **`503 Service Unavailable`**: The service is temporarily unable to handle the request due to maintenance or overload.


## cURL

```bash
# cURL example for POST /api/v1/calculate (Synchronous)
curl -X POST "https://prod.api.market/api/v1/kunstudio/saju-api/api/v1/calculate" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
        "year":1990,
        "month":5,
        "day":15,
        "hour":9,
        "gender":"M",
        "lang":"en"
      }'

# cURL example for POST /api/v1/interpret (Synchronous)
curl -X POST "https://prod.api.market/api/v1/kunstudio/saju-api/api/v1/interpret" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
        "year":1990,
        "month":5,
        "day":15,
        "hour":9,
        "gender":"M",
        "lang":"en"
      }'

# cURL example for POST /api/v1/compatibility (Synchronous)
curl -X POST "https://prod.api.market/api/v1/kunstudio/saju-api/api/v1/compatibility" \
  -H "Content-Type: application/json" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY" \
  -d '{
        "person_a": {"year":1990,"month":5,"day":15,"hour":9,"gender":"M"},
        "person_b": {"year":1992,"month":8,"day":3,"hour":14,"gender":"F"},
        "lang": "en"
      }'

# cURL example for GET /api/v1/daily (Synchronous)
curl -X GET "https://prod.api.market/api/v1/kunstudio/saju-api/api/v1/daily?day_master=%EA%B0%91&date=2026-07-07&lang=en" \
  -H "x-api-market-key: YOUR_API_MARKET_KEY"
```

## FAQ
**Q: What is Saju/BaZi?**

A: Saju (Korean, 사주팔자) and BaZi (Chinese) are traditional East Asian astrological systems that calculate a person's "Four Pillars of Destiny" based on their birth year, month, day, and hour. These pillars are then interpreted to understand an individual's personality, strengths, weaknesses, and life path.

**Q: How accurate is the Saju API?**

A: The Saju API is benchmark-verified against classical 만세력 (Ten-Thousand-Year Calendar) standards. This includes precise calculation of solar-term (절기) month boundaries, ensuring that pillar results match traditional professional Saju references rather than naive month calculations.

**Q: What languages does the API support?**

A: The API supports 10 languages for interpretations and summaries: Korean (ko), English (en), Japanese (ja), Chinese (zh), Spanish (es), Brazilian Portuguese (pt-br), Vietnamese (vi), Indonesian (id), Hindi (hi), and Thai (th).

**Q: What should I do if the birth hour is unknown?**

A: For the `hour` field in the `BirthRequest`, you can use `-1` if the exact birth hour is unknown. The API will proceed with calculations that do not require the hour pillar, or make reasonable assumptions where possible.

**Q: Are the dates input into the API solar or lunar?**

A: All dates provided to the API for birth information (`year`, `month`, `day`, `hour`) must be **solar (Gregorian)** dates. The API handles the conversion to the Saju/BaZi calendar internally, so you do not need to perform lunar-to-solar conversion yourself.

**Q: How do I get an API key?**

A: Your API key for the Saju API is issued by API.market when you subscribe to the service. This key (`x-api-market-key`) is essential for authentication and for billing your usage.

## Contact Us
If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to ghdejr11@gmail.com


Integrate the Saju API for accurate Korean Four Pillars and Chinese BaZi destiny calculations, two-person compatibility, and daily fortunes in 10 languages. Ben

Saju API: Korean Four Pillars, BaZi, Compatibility & Fortune

Free