운세 앱·사주 서비스 개발 — 명리 계산은 API로 끝내는 법 (SAZU 사주·만세력 API)

운세 앱 아이디어는 하루면 나옵니다. 문제는 그다음입니다. "생년월일시를 넣으면 사주팔자가 나온다" — 이 한 줄을 실제로 구현하려는 순간, 대부분의 프로젝트가 멈춥니다. 명리 계산은 캘린더 산수가 아니라 천문·역법·명리 규칙이 겹겹이 쌓인 도메인이기 때문입니다.

이 글은 사주·운세 서비스를 만들려는 개발자를 위해, 직접 구현이 왜 함정인지, 그리고 SAZU 사주·만세력 API가 그 전부를 REST 호출 한 번으로 어떻게 대신하는지 정리합니다. 무료 500건/월로 지금 바로 검증할 수 있습니다.

1. 사주 계산을 직접 짜면 마주치는 벽

"만세력 라이브러리 하나 붙이면 되겠지"라고 시작하지만, 정확한 사주 명식을 만들려면 아래가 모두 맞아야 합니다. 하나라도 어긋나면 결과 사주가 통째로 바뀝니다.

• 절기(節氣) 기준 월 판정 — 사주의 '월'은 달력의 월이 아니라 24절기로 나뉩니다. 입춘 전 출생은 전년도로 넘어갑니다.
• 진태양시·경도·균시차 보정 — 같은 시각이라도 태어난 도시에 따라 시주(時柱)가 갈립니다. 표준시로 계산하면 틀립니다.
• 음력 윤달·야자시 — 윤달 환산, 밤 11시 이후 날짜 전환(야자시) 처리가 빠지면 일주가 어긋납니다.
• 격국·용신·신살 — 명식이 나와도 그건 시작일 뿐입니다. 격국 판별, 억부·조후 용신, 귀인·살 판정은 명리 규칙서를 코드로 옮기는 별개의 프로젝트입니다.
• 장기 정확도 — 흔한 근사식은 1900~2100 구간에서 분 단위로 드리프트해, 경계 출생의 사주를 조용히 바꿔놓습니다.

여기에 검증까지 더하면 수 주가 사라집니다. 각도 wrap 버그, 절기 경계 off-by-one, 도시 좌표 관리… 정작 만들고 싶었던 '서비스'는 시작도 못 합니다.

2. SAZU 사주·만세력 API가 대신하는 것 — 14개 분석 모듈

SAZU API는 위 계산을 서버가 대신 책임지고, 결과를 구조화된 JSON으로 돌려줍니다. 명식 데이터뿐 아니라 명리 해석의 핵심 재료까지 14개 모듈로 제공합니다.

3. 호출은 이렇게 — 딱 한 번

생년월일시와 출생 도시만 넘기면 됩니다. 도시 경도·진태양시 보정은 서버가 자동 처리합니다.

POST https://api.sazu.app/v1/sazu/calculate
Content-Type: application/json
x-api-key: YOUR_API_KEY

{
  "birthYear": 1990, "birthMonth": 3, "birthDay": 15,
  "birthHour": 14, "birthMinute": 30,
  "isFemale": false,
  "isLunar": false,
  "birthCity": "서울",
  "trueSolarTime": true,
  "modules": ["fourPillars", "elements", "decadeFortune"]
}

필수는 birthYear·birthMonth·birthDay(camelCase, "birth" 접두사) 뿐입니다. 성별은 isFemale(불리언)로 넘기며, 대운 진행 방향·해석에 영향을 주므로 명시를 권장합니다. modules를 생략하면 플랜별 기본 모듈이, 지정하면 필요한 것만 응답에 담깁니다(응답 크기 최적화). birthCity는 71개 주요 도시를 내장해 한글·영문 어느 쪽으로 보내도 인식하고, 도시별 경도 보정을 자동 적용합니다.

4. 응답은 곧바로 화면에 붙일 수 있는 구조

파싱해서 가공할 필요 없이, 필드가 이미 명리 개념 그대로입니다. 예를 들어 사주 원국의 한 기둥은 이렇게 옵니다.

"year": {
  "full": "경오", "sky": "경", "earth": "오",
  "skyElement": "금", "earthElement": "화",
  "sippiSeong": "겁재", "twelveStage": "건록",
  "naeeum": "노방토",
  "jiJangGan": {
    "residue": { "stem": "병", "days": 10 },
    "middle":  { "stem": "기", "days": 9 },
    "main":    { "stem": "정", "days": 11 }
  }
}

오행 분포는 그대로 차트에 바인딩할 수 있습니다.

"fire":  { "name": "화", "total": { "count": 4, "percentage": 50.0 } },
"water": { "name": "수", "total": { "count": 0, "percentage": 0 } }

합형충파해·용신·격국·세운도 같은 방식으로 해석 텍스트와 관계 좌표를 함께 반환합니다. UI는 데이터 바인딩만 하면 됩니다.

5. 왜 정확한가 — 그리고 왜 캐시가 안전한가

• 진태양시 두 가지 모드 — 전통 관습(자시 23:30)과 천문학적 진태양시(경도+균시차)를 모두 지원. trueSolarTime 옵션 하나로 전환합니다.
• 절기·윤달·서머타임 자동 — 입춘 기준 월 판정, 음력 윤달, 과거 서머타임 구간까지 반영.
• 결정론적 응답 — 동일 입력은 항상 동일 출력입니다. 즉 응답을 안전하게 캐시할 수 있어, 반복 조회 비용을 0으로 만들 수 있습니다.
• 50ms 이하 응답 — 무거운 배치가 아니라 실시간 요청/응답에 맞는 지연 시간.

응답의 timezone 필드는 어떤 보정이 적용됐는지(도시 경도·균시차·최종 보정 분)를 투명하게 함께 돌려줘, 결과를 사용자에게 설명하기도 쉽습니다.

6. 어떤 팀이 SAZU API로 만들고 있나

"raw 명리 데이터"가 필요한 곳이면 어디에나 맞습니다. 대표적인 형태들:

• 운세 앱·웹 스타트업 — 명식 화면·오늘의 운세·궁합을 빠르게 출시하고, 엔진 대신 UX·마케팅에 집중.
• 상담사·역술인용 툴 — 만세력 조회, 격국·용신·신살 자동 판별로 상담 준비 시간을 단축하는 내부 도구.
• 챗봇·디스코드/카카오 봇 — 메시지로 생년월일을 받아 사주 요약을 돌려주는 봇. 결정론적 응답이라 캐시로 비용 절감.
• 이벤트·마케팅 페이지 — 신년 운세, 브랜드 콜라보 사주 이벤트처럼 단기 트래픽이 몰리는 캠페인.
• 사이드 프로젝트 — 무료 500건/월 안에서 아이디어를 실제 동작으로 검증하고, 반응이 오면 Pro로 확장.

공통점은 하나입니다 — 명리 엔진을 직접 만들지 않고, 만들고 싶었던 서비스부터 출시한다는 것.

7. 가격 — 무료로 시작해서 쓴 만큼

신용카드 없이 무료로 시작하고, 트래픽이 늘면 Pro로 넘어가면 됩니다. 테스트 호출도 quota에 차감되니, 성공 응답 형태를 한 번 확인한 뒤 실제 코드에 반영하세요.

8. 5분 시작 가이드

• ① 무료 가입 — API 키 발급은 무료이고 5분이면 끝납니다.
• ② 키 보관 — 키는 환경변수로 분리하고, 호출은 서버 사이드에서. 브라우저에 키를 노출하면 한도가 순식간에 소진됩니다.
• ③ 첫 호출 — /v1/sazu/calculate에 생년월일시+도시를 보내 응답을 확인.
• ④ 문서 참고 — API 문서에서 모듈별 응답 예시와 출생 도시·진태양시 옵션을 확인하세요.

자주 묻는 질문 (FAQ)

Q. 만세력 계산을 꼭 API로 해야 하나요?
A. 필수는 아니지만, 절기·진태양시·격국·용신·신살까지 정확히 직접 구현하고 검증하려면 수 주가 듭니다. SAZU API는 이 전부를 호출 한 번으로 제공하고, 무료 플랜으로 바로 검증할 수 있습니다.

Q. 출생 도시가 결과에 영향을 주나요?
A. 네. 도시 경도에 따라 진태양시가 달라져 시주가 바뀔 수 있습니다. SAZU API는 71개 도시 경도를 내장해 birthCity만 넘기면 자동 보정합니다.

Q. 응답을 캐시해도 되나요?
A. 됩니다. 동일 입력은 항상 동일 출력(결정론적)이라, 같은 사주 조회는 캐시로 비용을 0에 가깝게 만들 수 있습니다.

Q. 브라우저에서 직접 호출할 수 있나요?
A. 기본은 서버 사이드 호출을 권장합니다(키 노출 방지). 정적 사이트 등 불가피한 경우 Pro 키에 허용 도메인을 등록해 사용할 수 있습니다.

Q. 운세 '풀이 문장'까지 만들어주나요?
A. 이 API는 정확한 명리 데이터를 제공합니다. 완성된 운세 텍스트가 필요하면 프롬프트만 정의해 API로 받는 SAZU Studio가 있습니다 — 직접 개발이면 이 API, 노코드 완성형이면 Studio입니다.

마치며

운세 서비스의 승부는 명리 엔진을 얼마나 잘 짰는지가 아니라 사용자에게 무엇을 보여주는지에서 납니다. 계산은 SAZU가 책임질 테니, 여러분은 서비스에만 집중하세요.

👉 SAZU 사주·만세력 API 무료로 시작하기 · API 문서 · 노코드가 필요하면 SAZU Studio