만세력 API 응답 읽는 법, 원국·대운·근거 규칙 ID | 개발자 노트

사주 API를 처음 붙여 보면 응답이 생각보다 많아 보여서 어디부터 읽어야 할지 막막해요. 원국, 대운, 근거 규칙 ID가 한꺼번에 들어 있으니 화면에 무엇을 보여 줄지 정하기 어렵기도 해요. 오늘은 만세력 API 응답을 세 덩어리로 나눠서 읽는 방법을 정리해 볼게요.

결론부터 말씀드리면, 응답은 원국(무엇이 있나), 대운(언제 흐르나), 근거 규칙 ID(왜 그렇게 말하나) 순서로 읽으면 편해요. 이 순서를 따라가면 화면 설계도 자연스럽게 나와요.

이 글에 나오는 응답 형태는 설명을 위한 예시예요. 실제 필드 이름과 구조는 API 문서(https://hrum.ai/docs.html)에서 확인해 주세요.

01. 응답을 읽기 전에 알아 둘 것

HRUM의 사주 AI API는 만세력, 운 흐름, 궁합, 자미두수, 별자리, 평생사주, 꿈해몽, AI 사주 리딩을 제공해요. 이 글은 그 중 만세력과 운 흐름 응답을 중심으로 볼게요.

요금은 종량제 원화 크레딧으로 쓴 만큼 차감되는 구조예요. 그래서 개발 단계에서는 같은 요청을 여러 번 날리기보다, 응답 한 번을 저장해 두고 화면을 여러 번 그리는 방식이 비용 감각을 잡기 좋아요.

02. 응답 형태 예시

설명용으로 아주 단순하게 줄이면 아래와 같은 모양으로 생각하시면 돼요.

{"pillars": "…", "luck": "…", "ruleIds": ["…"]}

pillars에는 네 기둥, 곧 원국이 들어가고, luck에는 운의 흐름이 들어가고, ruleIds에는 풀이 근거 규칙 ID가 들어간다고 이해하시면 돼요. 값은 자리만 잡아 둔 것이에요.

03. 원국은 네 기둥에서 읽어요

원국은 년주, 월주, 일주, 시주 네 기둥을 말해요. 기둥마다 천간과 지지 두 글자가 있으니 전체가 여덟 글자예요. 화면에 보여 줄 때는 보통 네 기둥을 나란히 놓고, 일주의 천간을 일간으로 강조하는 방식이 많이 쓰여요.

시주는 출생 시각이 있어야 정확하게 나와요. 출생 시각이 비어 있거나 모르는 사용자라면, 시주를 빼고 보여 주는 화면을 따로 준비해 두는 게 좋아요. 입력이 빠진 상태를 자연스럽게 안내하면 사용자가 헷갈리지 않아요.

04. 운 흐름은 시작 나이와 순서로 읽어요

luck은 대운, 곧 10년 단위로 바뀌는 흐름을 담는다고 이해하시면 돼요. 화면에서는 현재 나이가 속한 대운을 먼저 강조하고, 그 앞뒤 대운을 작게 이어 보여 주면 흐름이 잘 읽혀요.

응답의 daeun 항목에는 구간마다 시작 나이(startAge)와 시작 연도(startYear)가 들어 있어요. 이 값을 그대로 쓰고, 앱에서 따로 계산하지 않는 쪽이 안전해요. 직접 계산 로직을 짜면 절입일 처리에서 차이가 생기기 쉬워요.

05. 근거 규칙 ID는 펼쳐 보는 용도로 써요

ruleIds는 풀이 문장이 어떤 규칙에서 나왔는지 추적하는 ID예요. 이 값이 있으면 풀이 문장을 내부에서 검수하거나, 화면에서 근거를 펼쳐 보여 주는 기능을 만들 수 있어요.

사용자 화면에서는 풀이 문장을 먼저 보여 주고, 근거 ID는 접어 두었다가 필요할 때 펼치는 구성이 읽기 편해요. 개발자 화면에서는 같은 ID가 어떤 결과에 반복해서 나오는지 모아 보면 풀이 품질을 점검하는 데 도움이 돼요.

근거 ID를 다루는 방식도 미리 정해 두면 좋아요. 예를 들어 ID 목록이 비어 있는 응답을 받았을 때 화면에 어떤 문구를 보여 줄지, 여러 ID가 붙었을 때 몇 개까지 펼칠지 같은 기준이에요. 이런 규칙을 앱 초반에 정해 두면 응답이 조금씩 달라져도 화면이 흔들리지 않아요.

06. 작은 앱으로 한 바퀴 돌려 보기

첫째, 콘솔 주소 https://console.hrum.ai 에서 계정을 만들고 사용 설정을 확인하세요. 둘째, 로컬에서 API를 한두 번 호출해 응답을 저장하고, 네 기둥과 운, 근거 ID가 어떻게 들어 오는지 눈으로 확인하세요. 셋째, 화면 하나짜리 앱을 만들고 응답을 그대로 보여 주는 뼈대를 짜세요.

넷째, 완성한 앱을 GitHub 저장소에 올린 뒤 RIDM Apps에 연결해 배포하세요. 배포가 끝나면 이름.ridm.ai 주소로 열리는지 확인하면 돼요. 앱마다 PostgreSQL 데이터베이스가 함께 붙으니, 저장한 응답이나 사용자 입력을 바로 넣어 볼 수 있어요.

07. 개발자가 챙길 점

인증에 쓰는 값은 저장소에 직접 넣지 말고 환경 변수로 관리하세요. 공개 저장소라면 특히 조심해야 해요. 또 사주 결과는 참고용이라는 안내 문구를 화면에 넣어 두는 것이 좋아요. 사주만으로 미래를 예측할 수 있다는 과학적 근거는 없으니, 결과를 단정하는 문장보다 근거를 함께 보여 주는 표현이 사용자와 서비스 모두를 지켜요.

정리하면, 원국은 네 기둥에서, 운은 시작 나이와 순서에서, 근거는 규칙 ID에서 읽으세요. 이 세 가지만 나눠 잡아도 응답이 훨씬 덜 복잡해 보여요. 처음부터 전체 응답을 한 화면에 다 넣으려 하기보다, 원국 카드 하나와 운 카드 하나로 시작해 점점 늘려 가는 방식을 권해요. 화면이 작은 단위로 자라면 어디서 무엇이 잘못되었는지도 금방 찾을 수 있어요.

※ 이 글의 응답 형태는 설명을 위한 예시이며 실제 구조가 아니에요. 사주 결과는 재미와 참고를 위한 것이에요. 최신 기능은 API 문서(https://hrum.ai/docs.html)에서, 요금은 콘솔에서 확인해 주세요.

이 콘텐츠에는 AI로 생성한 이미지·영상이 포함되어 있습니다.