Annual Profections API

전통 점성술의 Annual Profections는 매년 한 하우스씩 순환하며 그 해의 주요 테마를 나타냅니다. 현재 나이를 기준으로 활성화된 하우스, 별자리, 그리고 해당 연도의 룰러(지배 행성)를 계산합니다.

Profections 계산

POST/v1/astrology/profectionsClassical

주어진 나이에 대한 Profection 하우스, 별자리, 룰러를 계산합니다.

Annual Profections란?

Annual Profections는 헬레니즘 시대 점성술의 핵심 타이밍 기법입니다. 매년 1개 하우스씩 순환하며 (1세 = 1하우스, 2세 = 2하우스, ..., 13세 = 1하우스 재시작), 해당 연도의 주요 경험 영역을 나타냅니다.

Profected House: 현재 나이 % 12 + 1로 계산되는 하우스 번호
Profected Sign: 해당 하우스 커스프가 위치한 별자리
Profection Ruler: 그 별자리의 지배 행성 (Time Lord)

예를 들어, 35세의 경우 35 % 12 = 11, 11 + 1 = 12하우스가 활성화됩니다. 만약 12하우스 커스프가 처녀자리에 있다면, 그 해의 Profection Ruler는 수성(Mercury)이 됩니다.

요청 파라미터

파라미터

이름	타입	필수	설명
`natal_datetime`	`string`	필수	출생 날짜 및 시간 (ISO 8601 형식) 예시: `1990-06-15T14:30:00`
`natal_location`	`object`	필수	출생 위치 정보
`natal_location.latitude`	`number`	필수	위도 (-90 ~ 90) 예시: `37.5665`
`natal_location.longitude`	`number`	필수	경도 (-180 ~ 180) 예시: `126.9780`
`natal_location.timezone`	`string`	선택	IANA 타임존 (예: Asia/Seoul) - 미제공 시 좌표로 자동 감지 예시: `Asia/Seoul`
`current_age`	`integer`	필수	현재 나이 (0-120) 예시: `35`
`house_system`	`string`	선택	하우스 시스템 (PLACIDUS, WHOLE_SIGN, EQUAL 등) 예시: `PLACIDUS` 기본값: `PLACIDUS`
`name`	`string`	선택	차트 소유자 이름 예시: `Sample User`

요청 예시

curl -X POST https://api.destinyapi.com/v1/astrology/profections \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "natal_datetime": "1990-01-15T14:30:00",
  "natal_location": {
    "latitude": 37.5665,
    "longitude": 126.978,
    "timezone": "Asia/Seoul",
    "elevation": 38
  },
  "current_age": 35,
  "house_system": "PLACIDUS",
  "gender": "male",
  "name": "John Doe"
}'

타임존 자동 감지

natal_location.timezone을 제공하지 않으면 위도/경도 좌표를 기반으로 자동으로 타임존이 감지됩니다. 정확한 출생 시간대를 알고 있다면 명시적으로 제공하는 것을 권장합니다.

하우스 시스템

지원되는 하우스 시스템:

시스템	설명
`PLACIDUS`	가장 널리 사용되는 시간 기반 시스템 (기본값)
`WHOLE_SIGN`	헬레니즘 점성술의 전통 시스템 (Profections와 가장 자연스럽게 결합)
`EQUAL`	ASC에서 30도씩 균등 분할
`KOCH`	Koch 하우스 시스템
`CAMPANUS`	Campanus 하우스 시스템

응답 구조

성공 응답 (200)

성공 응답

응답 상태:200

{
  "success": true,
  "data": {
    "profection_info": {
      "current_age": 35,
      "profected_house_number": 12,
      "profected_sign": "Taurus",
      "profection_ruler": "Venus",
      "profected_cusp_longitude": 32.557781737403275,
      "calculation_date": "2025-11-12T03:59:43.828420"
    },
    "natal_chart_info": {
      "name": "John Doe",
      "datetime": "1990-01-15T14:30:00",
      "location": {
        "latitude": 37.5665,
        "longitude": 126.978,
        "timezone": "Asia/Seoul"
      },
      "house_system": "PLACIDUS"
    },
    "houses": {
      "house_1": {
        "cusp_longitude": 73.80217763515988,
        "sign": "Gemini"
      },
      "house_2": {
        "cusp_longitude": 96.2296514991633,
        "sign": "Cancer"
      },
      "house_3": {
        "cusp_longitude": 117.44718533695762,
        "sign": "Cancer"
      },
      "house_4": {
        "cusp_longitude": 141.5125975648466,
        "sign": "Leo"
      },
      "house_5": {
        "cusp_longitude": 172.51731593092222,
        "sign": "Virgo"
      },
      "house_6": {
        "cusp_longitude": 212.55778173740327,
        "sign": "Scorpio"
      },
      "house_7": {
        "cusp_longitude": 253.80217763515986,
        "sign": "Sagittarius"
      },
      "house_8": {
        "cusp_longitude": 276.2296514991633,
        "sign": "Capricorn"
      },
      "house_9": {
        "cusp_longitude": 297.4471853369576,
        "sign": "Capricorn"
      },
      "house_10": {
        "cusp_longitude": 321.5125975648466,
        "sign": "Aquarius"
      },
      "house_11": {
        "cusp_longitude": 352.5173159309222,
        "sign": "Pisces"
      },
      "house_12": {
        "cusp_longitude": 32.557781737403275,
        "sign": "Taurus"
      }
    },
    "interpretation": {
      "description": "At age 35, you are in a Taurus year, activating the 12th house themes.",
      "year_ruler": "Venus",
      "house_themes": "Spirituality, hidden matters, retreat, subconscious, solitude, endings",
      "note": "The profection ruler's natal condition and transits to it are especially important this year."
    }
  },
  "message": "Annual Profections calculated successfully",
  "timestamp": "2025-11-12T03:59:43.828436",
  "usage_info": {
    "feature": "profections",
    "user": "internal",
    "used": 0,
    "limit": 999999,
    "remaining": 999999
  }
}

응답 필드 설명

profection_info: Profections 계산 결과
- current_age: 입력된 현재 나이
- profected_house_number: 활성화된 하우스 번호 (1-12)
- profected_sign: 해당 하우스 커스프의 별자리
- profection_ruler: 그 해의 Time Lord (지배 행성)
- profected_cusp_longitude: 하우스 커스프의 경도 (도)
natal_chart_info: 출생 차트 기본 정보
houses: 전체 하우스 커스프 정보 (house_1 ~ house_12)
interpretation: 해당 연도에 대한 해석
usage_info: API 사용량 정보

하우스별 테마

각 하우스가 Profection으로 활성화될 때 강조되는 삶의 영역:

하우스	주요 테마
1하우스	자아, 정체성, 신체, 새로운 시작, 개인적 주도권
2하우스	자원, 돈, 소유물, 가치관, 자존감
3하우스	의사소통, 형제자매, 단거리 여행, 학습, 주변 환경
4하우스	가정, 가족, 뿌리, 부동산, 사적 영역, 감정적 기반
5하우스	창의성, 자녀, 로맨스, 즐거움, 자기표현, 투기
6하우스	일상, 건강, 직장, 서비스, 습관, 의무
7하우스	파트너십, 결혼, 관계, 계약, 공개적 적
8하우스	변화, 타인의 자원, 유산, 친밀감, 위기, 심리
9하우스	철학, 고등교육, 장거리 여행, 법률, 종교, 확장
10하우스	경력, 평판, 공적 지위, 성취, 권위, 목표
11하우스	친구, 네트워크, 집단, 희망, 사회적 목표
12하우스	영성, 은둔, 잠재의식, 고립, 끝맺음, 카르마

에러 응답

잘못된 나이 (400)

나이 범위 초과

응답 상태:400

{
  "success": false,
  "error": "Invalid value for 'body -> current_age': ensure this value is less than or equal to 120",
  "error_code": 400,
  "details": null,
  "timestamp": "2025-10-30T17:30:00.123456"
}

잘못된 날짜 형식 (400)

날짜 형식 오류

응답 상태:400

{
  "success": false,
  "error": "Invalid request data: Invalid isoformat string",
  "error_code": 400,
  "details": null,
  "timestamp": "2025-10-30T17:30:00.123456"
}

하우스 계산 실패 (500)

서버 오류

응답 상태:500

{
  "success": false,
  "error": "Failed to calculate Annual Profections. Please try again.",
  "error_code": 500,
  "details": null,
  "timestamp": "2025-10-30T17:30:00.123456"
}

에러 코드 요약

코드	설명	해결 방법
400	잘못된 요청 (나이 범위, 날짜 형식 등)	요청 파라미터를 확인하세요
401	인증 실패 (API 키 없음)	X-API-Key 헤더를 추가하세요
403	권한 없음 (profections 기능 미포함 플랜)	플랜을 업그레이드하세요
500	서버 내부 오류	잠시 후 다시 시도하거나 지원팀에 문의하세요

사용 팁

Whole Sign Houses 권장: Profections는 헬레니즘 기법이므로 Whole Sign 하우스와 가장 자연스럽게 결합됩니다.
Profection Ruler 추적: 그 해의 Profection Ruler 행성에 대한 트랜싯, 프로그레션을 특히 주의 깊게 관찰하세요.
생일 기준: Profections는 생일부터 다음 생일까지 1년 단위로 작동합니다.
다른 기법과 결합: Solar Return, Secondary Progressions, Transits와 함께 사용하면 더 풍부한 연간 전망을 얻을 수 있습니다.

DESTINYAPI · Developer Portal