> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sajuapi.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 사주 계산

생년월일시를 기반으로 사주팔자를 계산합니다.

<Warning>
  **권장**: 클라이언트에서 SajuCalculator.js를 사용하여 계산하는 것이 더 효율적입니다.
  이 엔드포인트는 서버사이드 계산이 필요한 경우에만 사용하세요.
</Warning>

***

## Request Body

<ParamField body="year" type="integer" required>
  출생 연도입니다. (예: 1990)
</ParamField>

<ParamField body="month" type="integer" required>
  출생 월입니다. (1-12)
</ParamField>

<ParamField body="day" type="integer" required>
  출생 일입니다. (1-31)
</ParamField>

<ParamField body="hour" type="integer">
  출생 시입니다. (0-23) 선택 사항입니다.
</ParamField>

<ParamField body="gender" type="string" required>
  성별입니다. `male` 또는 `female`입니다.
</ParamField>

***

## Response

### 성공

사주 계산에 성공하면 SajuResult 객체가 반환됩니다.

***

## 요청 예시

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch('/api/saju', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      year: 1990,
      month: 3,
      day: 15,
      hour: 14,
      gender: 'male'
    })
  });

  const saju = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://sajuapi.dev/api/saju',
      json={
          'year': 1990,
          'month': 3,
          'day': 15,
          'hour': 14,
          'gender': 'male'
      }
  )

  saju = response.json()
  ```

  ```bash cURL theme={null}
  curl -X POST https://sajuapi.dev/api/saju \
    -H "Content-Type: application/json" \
    -d '{
      "year": 1990,
      "month": 3,
      "day": 15,
      "hour": 14,
      "gender": "male"
    }'
  ```
</CodeGroup>

***

## 응답 예시

```json theme={null}
{
  "pillars": {
    "year": {
      "stem": {
        "kr": "경",
        "hangul": "경",
        "cn": "庚",
        "element": "metal",
        "elementKr": "금",
        "yinYang": "양",
        "index": 6
      },
      "branch": {
        "kr": "오",
        "hangul": "오",
        "cn": "午",
        "element": "fire",
        "elementKr": "화",
        "animal": "말",
        "index": 6
      },
      "fullKr": "경오",
      "fullCn": "庚午"
    },
    "month": {
      "stem": { "hangul": "기", "element": "earth" },
      "branch": { "hangul": "묘", "element": "wood" },
      "fullKr": "기묘",
      "fullCn": "己卯"
    },
    "day": {
      "stem": { "hangul": "병", "element": "fire" },
      "branch": { "hangul": "인", "element": "wood" },
      "fullKr": "병인",
      "fullCn": "丙寅"
    },
    "hour": {
      "stem": { "hangul": "을", "element": "wood" },
      "branch": { "hangul": "미", "element": "earth" },
      "fullKr": "을미",
      "fullCn": "乙未"
    }
  },
  "dayMaster": {
    "name": "병화",
    "element": "fire",
    "elementKr": "화",
    "yinYang": "양",
    "hangul": "병",
    "hanja": "丙"
  },
  "elements": {
    "wood": 3,
    "fire": 2,
    "earth": 2,
    "metal": 1,
    "water": 0
  },
  "dominantElement": "wood",
  "weakestElement": "water",
  "zodiac": "말",
  "gender": "male"
}
```

***

## SajuResult 객체

| 필드                | 타입     | 설명                           |
| ----------------- | ------ | ---------------------------- |
| `pillars`         | object | 사주 네 기둥 (년주, 월주, 일주, 시주)입니다. |
| `dayMaster`       | object | 일주 천간 정보입니다.                 |
| `elements`        | object | 오행별 개수입니다.                   |
| `dominantElement` | string | 가장 강한 오행입니다.                 |
| `weakestElement`  | string | 가장 약한 오행입니다.                 |
| `zodiac`          | string | 띠입니다.                        |
| `gender`          | string | 성별입니다.                       |

***

## 천간 (十天干)

| 한글 | 한자 | 오행   | 음양 |
| -- | -- | ---- | -- |
| 갑  | 甲  | 목(木) | 양  |
| 을  | 乙  | 목(木) | 음  |
| 병  | 丙  | 화(火) | 양  |
| 정  | 丁  | 화(火) | 음  |
| 무  | 戊  | 토(土) | 양  |
| 기  | 己  | 토(土) | 음  |
| 경  | 庚  | 금(金) | 양  |
| 신  | 辛  | 금(金) | 음  |
| 임  | 壬  | 수(水) | 양  |
| 계  | 癸  | 수(水) | 음  |

***

## 클라이언트 계산 (권장)

서버 API 대신 클라이언트에서 직접 계산하는 것이 더 효율적입니다.

```html theme={null}
<!-- SajuCalculator 로드 -->
<script src="/js/saju-calculator.js"></script>
```

```javascript theme={null}
// 클라이언트에서 계산
const saju = SajuCalculator.calculate({
  year: 1990,
  month: 3,
  day: 15,
  hour: 14,
  gender: 'male'
});

// 운세 API에 직접 사용
const fortune = await fetch('/api/daily-fortune', {
  method: 'POST',
  body: JSON.stringify({ saju, userName: '김철수', date: '2025-01-16' })
});
```

<Note>
  클라이언트 계산 시 서버 왕복이 줄어들어 응답 속도가 빨라집니다.
</Note>