역학 정보 API v1 문서

📋 목차

개요

• 양력/음력 변환: 양력 날짜를 음력으로, 음력 날짜를 양력으로 변환
• 간지 정보: 년주, 월주, 일주, 시주의 한자 및 한글 표기
• 24절기 정보: 해당 날짜의 절기 정보
• 나이 계산: 한국식 나이 및 만나이

---

기본 정보

Base URL:

https://weirdreports.com/pro/api/v1/calendar.php

요청 방법:
• HTTP Method: GET
• Content-Type: application/json
• 인코딩: UTF-8
• 버전: v1

---

엔드포인트

Calendar API

날짜 정보를 입력받아 양력, 음력, 간지, 24절기 정보를 반환합니다. URL:

GET /pro/api/v1/calendar.php

---

요청 파라미터

파라미터	타입	필수	기본값	설명
year	integer	✅	-	연도 (1900-2100)
month	integer	✅	-	월 (1-12)
day	integer	✅	-	일 (1-31)
hour	integer	❌	0	시 (0-23)
minute	integer	❌	0	분 (0-59)
type	integer	✅	-	1:양력, 2:음력
leapmonth	integer	❌	0	0:평달, 1:윤달 (음력일 경우)

파라미터 상세 설명

year (연도)
• 범위: 1900 ~ 2100
• 예시: 2000
month (월)
• 범위: 1 ~ 12
• 예시: 1 (1월), 12 (12월)
day (일)
• 범위: 1 ~ 31
• 실제 존재하는 날짜여야 함 (예: 2월 30일은 불가)
hour (시)
• 범위: 0 ~ 23
• 생략 시 0으로 처리
minute (분)
• 범위: 0 ~ 59
• 생략 시 0으로 처리
type (타입)
• 1: 양력 입력 (양력을 음력으로 변환)
• 2: 음력 입력 (음력을 양력으로 변환)
leapmonth (윤달)
• 0: 평달
• 1: 윤달
• 음력(type=2)일 경우에만 의미가 있음

---

응답 형식

성공 응답

HTTP Status: 200 OK 응답 예시:

{
  "success": true,
  "data": {
    "solar": {
      "year": 2000,
      "month": 1,
      "day": 1,
      "hour": 12,
      "minute": 0
    },
    "lunar": {
      "year": 1999,
      "month": 11,
      "day": 25,
      "leapMonth": false
    },
    "solarTerm": {
      "name": "소한",
      "nameHan": "小寒",
      "year": 2000,
      "month": 1,
      "day": 6,
      "hour": 9,
      "minute": 30
    },
    "ganzhi": {
      "si": "庚申",
      "il": "甲子",
      "wo": "丁丑",
      "se": "己卯",
      "siKor": "경신",
      "ilKor": "갑자",
      "woKor": "정축",
      "seKor": "기묘"
    },
    "age": {
      "korean": 25,
      "man": 24
    }
  }
}

응답 필드 설명

solar (양력)
• year: 연도
• month: 월
• day: 일
• hour: 시
• minute: 분
lunar (음력)
• year: 연도
• month: 월
• day: 일
• leapMonth: 윤달 여부 (boolean)
solarTerm (24절기)
• name: 절기 이름 (한글)
• nameHan: 절기 이름 (한자)
• year, month, day, hour, minute: 절기 날짜 및 시간
ganzhi (간지)
• si: 시주 (한자)
• il: 일주 (한자)
• wo: 월주 (한자)
• se: 세주/년주 (한자)
• siKor, ilKor, woKor, seKor: 각각의 한글 표기
age (나이)
• korean: 한국식 나이
• man: 만나이

에러 응답

HTTP Status: 200 OK (에러도 200으로 반환, success: false로 구분) 응답 예시:

{
  "success": false,
  "error": "유효하지 않은 날짜입니다.",
  "code": "INVALID_DATE"
}

---

사용 예시

예시 1: 양력 날짜 조회

요청:

GET /pro/api/v1/calendar.php?year=2000&month=1&day=1&type=1

응답:

{
  "success": true,
  "data": {
    "solar": {
      "year": 2000,
      "month": 1,
      "day": 1,
      "hour": 0,
      "minute": 0
    },
    "lunar": {
      "year": 1999,
      "month": 11,
      "day": 25,
      "leapMonth": false
    },
    ...
  }
}

예시 2: 음력 날짜 조회

요청:

GET /pro/api/v1/calendar.php?year=2000&month=1&day=1&type=2

예시 3: 시간 포함 조회

요청:

GET /pro/api/v1/calendar.php?year=2000&month=1&day=1&hour=12&minute=30&type=1

예시 4: JavaScript에서 사용

fetch('https://weirdreports.com/pro/api/v1/calendar.php?year=2000&month=1&day=1&type=1')
  .then(response => response.json())
  .then(data => {
    if (data.success) {
      console.log('양력:', data.data.solar);
      console.log('음력:', data.data.lunar);
      console.log('간지:', data.data.ganzhi);
    } else {
      console.error('에러:', data.error);
    }
  })
  .catch(error => {
    console.error('요청 실패:', error);
  });

예시 5: cURL로 테스트

curl "https://weirdreports.com/pro/api/v1/calendar.php?year=2000&month=1&day=1&type=1"

---

에러 코드

코드	설명	해결 방법
INVALID_YEAR	연도가 1900-2100 범위를 벗어남	올바른 연도 입력
INVALID_MONTH	월이 1-12 범위를 벗어남	올바른 월 입력
INVALID_DAY	일이 1-31 범위를 벗어남	올바른 일 입력
INVALID_DATE	존재하지 않는 날짜	실제 존재하는 날짜 입력
EXCEPTION	일반 예외 발생	서버 로그 확인
ERROR	시스템 오류	관리자에게 문의

---

제한 사항

현재 서비스 제공 범위

기본 날짜 계산:
• ✅ 기본 API 구조
• ✅ 유효성 검사
• ✅ 나이 계산
• ✅ 에러 처리
역학 제공 정보:
• 🔄 양력/음력 변환 출력
• 🔄 한자/한글 간지 출력
• 🔄 24절기 정보 제공
향후 추가 가능:
• 📅 API 인증 시스템 (API Key)
• 📅 Rate Limiting (사용량 제한)
• 📅 프리미엄 기능
• 📅 구독 모델

사용 주의사항

현재는 무료로 제공되며, 별도의 사용 제한은 없습니다. 다만, 서버 부하를 고려하여 과도한 요청은 자제해주시기 바랍니다.

향후 추가 가능

향후 다음과 같은 제한이 도입될 수 있습니다:
• 분당/일일/월별 요청 횟수 제한
• API Key 인증 필수로 변경 등등

문의 및 지원

라이선스