API 문서

사주 명식, 궁합, 오늘의 운세, 자미두수, 만세력을 HTTP로 부르는 API예요. 테스트 키를 받으면 아래 예제 코드에 키가 자동으로 들어가고, 이 페이지에서 바로 호출해 볼 수 있어요.

시작하기

  1. 테스트 키 받기 — 메일 주소만 넣으면 바로 나와요. 7일 동안 30번 호출할 수 있어요.
  2. 호출하기 — 요청 헤더에 Authorization: Bearer 테스트 키를 넣고 JSON으로 보내요.
  3. 마음에 들면 구매 — 같은 요청·응답 형식의 서버가 파일로 들어 있어요. 내 서버에서 키 없이, 횟수 제한 없이 돌려요.

테스트 키 발급

인증과 제한

Base URLhttps://sajuaedam.kro.kr/kit/api/v1
인증Authorization: Bearer sk_trial_…
요청POST /도구 이름, 본문은 JSON(UTF-8)
응답JSON. 헤더 X-Trial-Remaining에 남은 호출 수
한도키 하나에 7일·30번. 어떤 도구든 호출 한 번에 1번 차감. 분당 60번까지
키 발급메일 주소 하나에 한 번
도구 목록GET https://sajuaedam.kro.kr/kit/api/v1/tools (키 없이, 입력 스키마 포함)

요청에 넣은 생년월일은 계산에만 쓰고 저장하지 않아요.

오류

오류는 {"error": "설명"} 형식으로 와요.

상태뜻
400입력이 잘못됨(날짜 형식, 없는 도시 등). 메시지에 이유가 있어요
401키가 없거나 잘못됨
403체험 기간이 끝남
404없는 도구 이름
429호출 횟수를 다 씀, 또는 너무 빠르게 호출함

사주 명식 POST /kit/api/v1/saju_chart

사주 명식을 계산한다(한국천문연구원 기준 음양력, 과거 표준시·서머타임·경도 보정). 네 기둥·십성·12운성·지장간·납음·신살·합충·오행·강약·용신·격국·대운·세운과 주제별 해석 지표(성향·직업·재물·관계·건강·시기)를 돌려준다.

요청 본문

이름형식설명
birthstring필수생년월일 YYYY-MM-DD
timestring선택출생 시각 HH:mm (24시간). 모르면 생략
calendar"solar" | "lunar" | "lunar-leap"선택양력(solar)·음력(lunar)·음력 윤달(lunar-leap). 기본 solar
gender"male" | "female"필수
citystring선택출생 도시 이름(예: 서울, 부산, New York). 기본 서울
namestring선택표시용 이름(선택)
asOfstring선택기준 시각 ISO 8601(오프셋 포함). 기본 현재 시각
ratHourRule"jasi-day-change" | "split-jasi" | "midnight"선택자시 관법. 기본 jasi-day-change(자시 일변경)
format"summary" | "full"선택summary(기본): 해석 지표+TOON 텍스트, full: 원본 명식 JSON까지

예시 요청

curl -X POST https://sajuaedam.kro.kr/kit/api/v1/saju_chart \
  -H "Authorization: Bearer YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birth":"1992-10-24","time":"09:10","gender":"female","city":"서울","asOf":"2026-10-01T00:00:00+09:00"}'
예시 응답 보기
{
  "analysis": {
    "version": "saju-analysis-v1",
    "gender": "female",
    "timeKnown": true,
    "dayMaster": {
      "stem": "계",
      "element": "수",
      "polarity": "음",
      "meaning": {
        "id": "gye",
        "korean": "계수",
        "hanja": "癸水",
        "image": "이슬비와 샘물",
        "strengths": [
          "섬세한 통찰",
          "적응",
          "조용한 설득"
        ],
        "cautions": [
          "불안",
          "생각이 많음"
        ]
      },
      "tier": "calculated"
    },
    "pillars": [
      {
        "kind": "year",
        "pillar": "임신",
        "stemTenGod": "겁재",
        "branchTenGod": "정인",
        "twelveStage": "사"
      },
      {
        "kind": "month",
        "pillar": "경술",
        "stemTenGod": "정인",
        "branchTenGod": "정관",
        "twelveStage": "쇠"
      },
      {
        "kind": "day",
        "pillar": "계유",
        "stemTenGod": null,
        "branchTenGod": "편인",
        "twelveStage": "병"
      },
      {
        "kind": "hour",
        "pillar": "병진",
        "stemTenGod": "정재",
        "branchTenGod": "정관",
        "twelveStage": "양"
      }
    ],
    "elements": [
      {
        "element": "목",
        "elementId": "wood",
        "percent": 0,
        "level": "없음"
      },
      {
        "element": "화",
        "elementId": "fire",
        "percent": 8.7,
        "level": "부족"
      },
      {
        "element": "토",
        "elementId": "earth",
        "percent": 39.13,
        "level": "과다"
      },
      {
        "element": "금",
        "elementId": "metal",
        "percent": 34.78,
        "level": "발달"
      },
      {
        "element": "수",
        "elementId": "water",
        "percent": 17.39,
        "level": "적정"
      }
    ],
    "missingElements": [
      "목"
    ],
    "excessiveElements": [
      "토"
    ],
    "tenGodGroups": [
      {
        "group": "비겁",
        "element": "수",
        "percent": 17.4
      },
      {
        "group": "식상",
        "element": "목",
        "percent": 0
      },
      {
        "group": "재성",
        "element": "화",
        "percent": 8.69
      },
      {
        "group": "관성",
        "element": "토",
        "percent": 39.13
      },
      {
        "group": "인성",
        "element": "금",
        "percent": 34.78
      }
… (길어서 앞부분만 보여 줘요. 전체는 아래에서 직접 호출해 보세요)

직접 호출해 보기 (1번 차감)

궁합 POST /kit/api/v1/compatibility

두 사람의 사주 궁합 점수(100점, 항목별 근거·분위)와 띠·일주·교차 십성을 계산한다.

요청 본문

이름형식설명
a.birthstring필수생년월일 YYYY-MM-DD
a.timestring선택출생 시각 HH:mm (24시간). 모르면 생략
a.calendar"solar" | "lunar" | "lunar-leap"선택양력(solar)·음력(lunar)·음력 윤달(lunar-leap). 기본 solar
a.gender"male" | "female"필수
a.citystring선택출생 도시 이름(예: 서울, 부산, New York). 기본 서울
a.namestring선택표시용 이름(선택)
b.birthstring필수생년월일 YYYY-MM-DD
b.timestring선택출생 시각 HH:mm (24시간). 모르면 생략
b.calendar"solar" | "lunar" | "lunar-leap"선택양력(solar)·음력(lunar)·음력 윤달(lunar-leap). 기본 solar
b.gender"male" | "female"필수
b.citystring선택출생 도시 이름(예: 서울, 부산, New York). 기본 서울
b.namestring선택표시용 이름(선택)
asOfstring선택기준 시각 ISO 8601(오프셋 포함). 기본 현재 시각
ratHourRule"jasi-day-change" | "split-jasi" | "midnight"선택자시 관법. 기본 jasi-day-change(자시 일변경)

예시 요청

curl -X POST https://sajuaedam.kro.kr/kit/api/v1/compatibility \
  -H "Authorization: Bearer YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"a":{"birth":"1992-10-24","time":"09:10","gender":"female","city":"서울"},"b":{"birth":"1990-05-15","time":"14:30","gender":"male","city":"부산"},"asOf":"2026-10-01T00:00:00+09:00"}'
예시 응답 보기
{
  "score": {
    "score": 76,
    "rawScore": 76,
    "grade": "잘 맞는 편",
    "items": [
      {
        "key": "day-stem",
        "label": "일간 관계",
        "score": 19,
        "max": 25,
        "reason": "수와 금은 서로 살려주는 사이입니다. 두 번째 사람 쪽이 기운을 내줍니다. 음양이 서로 달라 자리를 나누기 쉽습니다.",
        "band": "높은 편"
      },
      {
        "key": "spouse-palace",
        "label": "배우자궁",
        "score": 45,
        "max": 45,
        "reason": "두 사람의 일지가 酉辰 육합입니다. 배우자궁이 직접 맞물리는 자리라 생활 리듬이 잘 붙습니다. 궁합에서 가장 무겁게 보는 조합입니다.",
        "band": "아주 높은 편"
      },
      {
        "key": "outer-match",
        "label": "겉궁합",
        "score": 4,
        "max": 10,
        "reason": "월지에 戌巳 마찰입니다. 겉궁합은 두 사람이 바깥에서 어떻게 어울리는지를 보는 자리라, 속궁합보다 가볍게 봅니다.",
        "band": "보통"
      },
      {
        "key": "element-balance",
        "label": "오행 보완",
        "score": 8,
        "max": 20,
        "reason": "첫 번째 사람에게 필요한 화·토 기운을 두 번째 사람이 넉넉히 갖고 있습니다. 다만 둘을 합쳐도 목 기운은 얕게 남습니다. 상대에게만 기대기보다 각자의 취미와 생활 습관으로 보완해 보세요.",
        "band": "낮은 편"
      }
    ],
    "band": "아주 높은 편",
    "verdict": {
      "headline": "뜻도 생활도 같은 쪽을 봅니다",
      "reading": "첫 번째 사람과 두 번째 사람은 판단이 모이는 자리와 하루를 보내는 자리가 함께 맞물립니다. 말이 통해서 편한 것과 같이 지내서 편한 것이 겹치는 경우는 흔하지 않습니다. 다만 겹치는 만큼 서로의 문제를 자기 문제로 끌어안기 쉬워, 각자의 몫을 구분해 두는 편이 오래갑니다.",
      "watchFor": "갈등이 났을 때 얼마 만에 다시 말을 거는지 서로 확인해 두세요. 잘 맞는 관계일수록 문제는 크기가 아니라 회복에 걸리는 시간에서 드러납니다."
    },
    "heuristic": true,
    "rulesVersion": "compatibility-score-v5"
  },
  "zodiac": {
    "a": "신",
    "b": "오",
    "relations": []
  },
  "dayPillars": {
    "a": "계유",
    "b": "경진",
    "stemRelation": null,
    "branchRelations": [
      "육합"
    ]
  },
  "crossTenGods": {
    "bForA": {
      "tenGod": "정인",
      "group": "인성",
      "isSpouseStar": false
    },
    "aForB": {
      "tenGod": "상관",
      "group": "식상",
      "isSpouseStar": false
    }
  },
  "heuristic": true
}

직접 호출해 보기 (1번 차감)

오늘의 운세 POST /kit/api/v1/daily_fortune

특정 날짜의 일진 운세 점수(0~100, 분위 띠)와 근거, 중점 분야, 행운 색·수·방위·시간을 계산한다.

요청 본문

이름형식설명
birthstring필수생년월일 YYYY-MM-DD
timestring선택출생 시각 HH:mm (24시간). 모르면 생략
calendar"solar" | "lunar" | "lunar-leap"선택양력(solar)·음력(lunar)·음력 윤달(lunar-leap). 기본 solar
gender"male" | "female"필수
citystring선택출생 도시 이름(예: 서울, 부산, New York). 기본 서울
namestring선택표시용 이름(선택)
asOfstring선택기준 시각 ISO 8601(오프셋 포함). 기본 현재 시각
ratHourRule"jasi-day-change" | "split-jasi" | "midnight"선택자시 관법. 기본 jasi-day-change(자시 일변경)
datestring선택YYYY-MM-DD. 기본 오늘

예시 요청

curl -X POST https://sajuaedam.kro.kr/kit/api/v1/daily_fortune \
  -H "Authorization: Bearer YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birth":"1992-10-24","time":"09:10","gender":"female","city":"서울","date":"2026-10-01"}'
예시 응답 보기
{
  "rulesVersion": "daily-fortune-v1",
  "date": "2026-10-01",
  "dayPillar": "무신",
  "stemTenGod": "정관",
  "branchTenGod": "정인",
  "twelveStage": "사",
  "score": 38,
  "band": "신중",
  "focusDomains": [
    "일·책임",
    "평판",
    "공부·문서",
    "휴식·회복"
  ],
  "factors": [
    {
      "code": "excessive-branch",
      "points": -10,
      "text": "일진 지지가 넘치는 기운(금)"
    },
    {
      "code": "day-stem-combination",
      "points": 4,
      "text": "일진 천간이 일간과 합"
    },
    {
      "code": "twelve-stage",
      "points": -6,
      "text": "일간의 기세 사"
    }
  ],
  "lucky": {
    "element": "목",
    "colors": [
      "초록",
      "청색"
    ],
    "numbers": [
      3,
      8
    ],
    "direction": "동쪽",
    "hours": [
      "03~05시",
      "05~07시"
    ]
  },
  "heuristic": true
}

직접 호출해 보기 (1번 차감)

만세력 달력 POST /kit/api/v1/calendar_month

한 달치 만세력 달력: 양력·음력(윤달)·일진·절기·손없는날.

요청 본문

이름형식설명
yearinteger필수
monthinteger필수

예시 요청

curl -X POST https://sajuaedam.kro.kr/kit/api/v1/calendar_month \
  -H "Authorization: Bearer YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"month":10}'
예시 응답 보기
[
  {
    "solar": "2026-10-01",
    "weekday": "목",
    "lunar": {
      "year": 2026,
      "month": 8,
      "day": 21,
      "isLeapMonth": false
    },
    "dayPillar": "무신",
    "dayPillarHanja": "戊申",
    "yearOfZodiac": "말",
    "solarTerm": null,
    "sonEopneun": false,
    "sonDirection": "동쪽"
  },
  {
    "solar": "2026-10-02",
    "weekday": "금",
    "lunar": {
      "year": 2026,
      "month": 8,
      "day": 22,
      "isLeapMonth": false
    },
    "dayPillar": "기유",
    "dayPillarHanja": "己酉",
    "yearOfZodiac": "말",
    "solarTerm": null,
    "sonEopneun": false,
    "sonDirection": "동쪽"
  },
  {
    "solar": "2026-10-03",
    "weekday": "토",
    "lunar": {
      "year": 2026,
      "month": 8,
      "day": 23,
      "isLeapMonth": false
    },
    "dayPillar": "경술",
    "dayPillarHanja": "庚戌",
    "yearOfZodiac": "말",
    "solarTerm": null,
    "sonEopneun": false,
    "sonDirection": "남쪽"
  },
  {
    "solar": "2026-10-04",
    "weekday": "일",
    "lunar": {
      "year": 2026,
      "month": 8,
      "day": 24,
      "isLeapMonth": false
    },
    "dayPillar": "신해",
    "dayPillarHanja": "辛亥",
    "yearOfZodiac": "말",
    "solarTerm": null,
    "sonEopneun": false,
    "sonDirection": "남쪽"
  },
  {
    "solar": "2026-10-05",
    "weekday": "월",
    "lunar": {
      "year": 2026,
      "month": 8,
      "day": 25,
      "isLeapMonth": false
    },
    "dayPillar": "임자",
    "dayPillarHanja": "壬子",
    "yearOfZodiac": "말",
    "solarTerm": null,
    "sonEopneun": false,
    "sonDirection": "서쪽"
  },
  {
    "solar": "2026-10-06",
    "weekday": "화",
    "lunar": {
      "year": 2026,
      "month": 8,
      "day": 26,
      "isLeapMonth": false
    },
    "dayPillar": "계축",
    "dayPillarHanja": "癸丑",
    "yearOfZodiac": "말",
    "solarTerm": null,
    "sonEopneun": false,
    "sonDirection": "서쪽"
  },
  {
    "solar": "2026-10-07",
    "weekday": "수",
    "lunar": {
      "year": 2026,
      "month": 8,
      "day": 27,
      "isLeapMonth": false
    },
    "dayPillar": "갑인",
    "dayPillarHanja": "甲寅",
    "yearOfZodiac": "말",
    "solarTerm": null,
    "sonEopneun": false,
    "sonDirection": "북쪽"
  },
  {
    "solar": "2026-10-08",
    "weekday": "목",
    "lunar": {
      "year": 2026,
      "month": 8,
      "day": 28,
… (길어서 앞부분만 보여 줘요. 전체는 아래에서 직접 호출해 보세요)

직접 호출해 보기 (1번 차감)

자미두수 명반 POST /kit/api/v1/ziwei_chart

자미두수 명반을 한국 음력 기준으로 계산한다. 출생 시각이 필요하다.

요청 본문

이름형식설명
birthstring필수생년월일 YYYY-MM-DD
timestring선택출생 시각 HH:mm (24시간). 모르면 생략
calendar"solar" | "lunar" | "lunar-leap"선택양력(solar)·음력(lunar)·음력 윤달(lunar-leap). 기본 solar
gender"male" | "female"필수
citystring선택출생 도시 이름(예: 서울, 부산, New York). 기본 서울
namestring선택표시용 이름(선택)
asOfstring선택기준 시각 ISO 8601(오프셋 포함). 기본 현재 시각
ratHourRule"jasi-day-change" | "split-jasi" | "midnight"선택자시 관법. 기본 jasi-day-change(자시 일변경)

예시 요청

curl -X POST https://sajuaedam.kro.kr/kit/api/v1/ziwei_chart \
  -H "Authorization: Bearer YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birth":"1992-10-24","time":"09:10","gender":"female","city":"서울","asOf":"2026-10-01T00:00:00+09:00"}'
예시 응답 보기
{
  "overview": {
    "releaseStatus": "experimental",
    "convention": "korean-ziwei-v1@0.1.0",
    "lifePalace": {
      "id": "life",
      "name": "명궁",
      "branch": "오",
      "master": "파군"
    },
    "bodyPalace": {
      "id": "money",
      "name": "재백궁",
      "branch": "인",
      "master": "천량"
    },
    "bureau": {
      "id": "water-2",
      "value": 2
    },
    "palaces": [
      {
        "id": "money",
        "name": "재백궁",
        "branch": "인",
        "majorStars": [
          "천기",
          "태음"
        ],
        "auxiliaryStars": [
          "우필",
          "천마",
          "영성"
        ]
      },
      {
        "id": "children",
        "name": "자녀궁",
        "branch": "묘",
        "majorStars": [
          "자미",
          "탐랑"
        ],
        "auxiliaryStars": [
          "천괴",
          "지겁"
        ]
      },
      {
        "id": "spouse",
        "name": "부처궁",
        "branch": "진",
        "majorStars": [
          "거문"
        ],
        "auxiliaryStars": []
      },
      {
        "id": "siblings",
        "name": "형제궁",
        "branch": "사",
        "majorStars": [
          "천상"
        ],
        "auxiliaryStars": [
          "천월"
        ]
      },
      {
        "id": "life",
        "name": "명궁",
        "branch": "오",
        "majorStars": [
          "천량"
        ],
        "auxiliaryStars": [
          "문창",
          "화성"
        ]
      },
      {
        "id": "parents",
        "name": "부모궁",
        "branch": "미",
        "majorStars": [
          "염정",
          "칠살"
        ],
        "auxiliaryStars": [
          "지공"
        ]
      },
      {
        "id": "wellbeing",
        "name": "복덕궁",
        "branch": "신",
        "majorStars": [],
        "auxiliaryStars": [
          "문곡"
        ]
      },
      {
        "id": "property",
        "name": "전택궁",
        "branch": "유",
        "majorStars": [],
        "auxiliaryStars": []
      },
      {
        "id": "career",
        "name": "관록궁",
        "branch": "술",
        "majorStars": [
          "천동"
        ],
        "auxiliaryStars": [
          "타라"
        ]
      },
      {
… (길어서 앞부분만 보여 줘요. 전체는 아래에서 직접 호출해 보세요)

직접 호출해 보기 (1번 차감)

음력↔양력 변환 POST /kit/api/v1/convert_date

양력↔한국 음력 변환(1900~2100). solar 또는 lunar 중 하나를 준다.

요청 본문

이름형식설명
solarstring선택양력 YYYY-MM-DD
lunarstring선택음력 YYYY-MM-DD
leapboolean선택음력 윤달 여부

예시 요청

curl -X POST https://sajuaedam.kro.kr/kit/api/v1/convert_date \
  -H "Authorization: Bearer YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lunar":"2023-02-10","leap":true}'
예시 응답 보기
{
  "lunar": "2023-02-10",
  "leap": true,
  "solar": "2023-03-31"
}

직접 호출해 보기 (1번 차감)

도시 찾기 POST /kit/api/v1/search_city

출생 도시를 검색한다(국내 6.3만·해외 3.4만 곳, 경위도·IANA 시간대 포함).

요청 본문

이름형식설명
querystring필수
limitinteger선택

예시 요청

curl -X POST https://sajuaedam.kro.kr/kit/api/v1/search_city \
  -H "Authorization: Bearer YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"부산","limit":3}'
예시 응답 보기
[
  {
    "geonameId": 1838519,
    "fullName": "대한민국, 부산광역시",
    "name": "부산광역시",
    "country": "대한민국",
    "countryCode": "KR",
    "admin1": "부산광역시",
    "latitude": 35.13333,
    "longitude": 129.05,
    "timeZone": "Asia/Seoul",
    "population": 3343903
  },
  {
    "geonameId": 1838523,
    "fullName": "대한민국, 경상남도, 부산",
    "name": "부산",
    "country": "대한민국",
    "countryCode": "KR",
    "admin1": "경상남도",
    "latitude": 35.70128,
    "longitude": 128.02524,
    "timeZone": "Asia/Seoul",
    "population": 0
  },
  {
    "geonameId": 6890280,
    "fullName": "대한민국, 경상북도, 부산",
    "name": "부산",
    "country": "대한민국",
    "countryCode": "KR",
    "admin1": "경상북도",
    "latitude": 36.3809,
    "longitude": 128.3681,
    "timeZone": "Asia/Seoul",
    "population": 0
  }
]

직접 호출해 보기 (1번 차감)

구매 후: 내 서버에서

구매한 파일에는 같은 요청·응답 형식의 서버가 들어 있어요. 켜면 키 없이, 횟수 제한 없이, 인터넷 없이 돌아요.

node --experimental-strip-types server/http.ts
# → http://localhost:8787/api/tools

curl -X POST http://localhost:8787/api/saju_chart \
  -H "Content-Type: application/json" \
  -d '{"birth":"1992-10-24","time":"09:10","gender":"female","city":"서울"}'

체험 API의 https://sajuaedam.kro.kr/kit/api/v1/도구를 http://localhost:8787/api/도구로 바꾸고 인증 헤더만 빼면 돼요. Claude·Cursor에는 MCP 서버로도 붙일 수 있어요.

가격 보기