Primary Directions API
프라이머리 디렉션(Primary Directions)은 고전 점성술의 가장 오래된 예측 기법 중 하나로, 출생 후 시간의 흐름에 따라 천체들이 "상징적으로" 이동하는 위치를 계산합니다. 1도 = 1년의 원리를 사용하여 인생의 주요 사건과 전환점을 예측합니다.
프라이머리 디렉션 계산
/v1/astrology/directionsClassical특정 나이의 프라이머리 디렉션 위치와 네이탈 차트와의 애스펙트를 계산합니다.
프라이머리 디렉션이란?
프라이머리 디렉션은 지구의 자전을 기반으로 한 계산 방식으로, 출생 후 4분이 인생의 1년을 상징합니다. 이는 다음과 같은 천문학적 원리에 기초합니다:
- 1도 = 1년: 천체가 1도 이동하는 것이 1년의 시간을 의미
- 고전 기법: 중세 및 고대 점성술에서 가장 중요하게 여겨진 예측 방법
- 정확성: 출생 시간이 정확할수록 더 정밀한 예측 가능
- Semi-arc 방식: Ptolemy, Placidus, Regiomontanus 등 다양한 계산법 존재
계산 예시
1990년 6월 15일에 태어난 사람의 30세 디렉션을 계산하면, 각 천체가 출생 위치에서 30도씩 "상징적으로" 이동한 위치를 찾습니다. 예를 들어 네이탈 태양이 쌍둥이자리 23도라면, 30세 때의 디렉션 태양은 게자리 23도에 위치합니다. 이 디렉션 태양이 네이탈 금성과 합을 이루면 그 해에 중요한 사랑이나 창조적 사건이 발생할 수 있습니다.
프라이머리 디렉션 vs 2차 진행
| 구분 | 프라이머리 디렉션 | 2차 진행 |
|---|---|---|
| 기본 원리 | 지구 자전 (1도 = 1년) | 지구 공전 (1일 = 1년) |
| 역사 | 고대~중세 점성술의 주류 기법 | 근대 이후 널리 사용 |
| 계산 복잡도 | 복잡 (Semi-arc, 구면삼각법) | 단순 (일자 계산) |
| 이동 속도 | 모든 천체 균일 (1도/년) | 천체마다 다름 (태양 1도/년, 달 13도/월) |
| 적용 분야 | 주요 인생 사건, 전환점 | 내적 발달, 심리적 변화 |
| 정확도 요구 | 매우 높음 (분 단위 정확성) | 상대적으로 유연 |
디렉션 방법 비교
| 방법 | 설명 | 특징 |
|---|---|---|
| Ptolemy (Ptosimiare) | 톨레미의 Semi-arc 방식 | 가장 전통적, 구면삼각법 사용 |
| Placidus | 플라시더스 하우스 시스템 기반 | 시간 기반 디렉션 |
| Regiomontanus | 레지오몬타누스 방식 | 공간 기반 디렉션 |
| Naibod | 나이보드 키 (1° = 1년 정확) | 단순화된 현대적 접근 |
요청 파라미터
파라미터
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
natal_datetime | string | 필수 | 출생 날짜 및 시간 (ISO 8601 형식) 예시: |
natal_location | object | 필수 | 출생 위치 정보 |
natal_location.latitude | number | 필수 | 위도 (-90 ~ 90) 예시: |
natal_location.longitude | number | 필수 | 경도 (-180 ~ 180) 예시: |
natal_location.timezone | string | 선택 | IANA 타임존 (예: Asia/Seoul) - 미제공 시 좌표로 자동 감지 예시: |
target_age | number | 선택 | 대상 나이 (소수점 가능, 예: 25.5) - target_date와 둘 중 하나 필수 예시: |
target_date | string | 선택 | 대상 날짜 (YYYY-MM-DD 또는 ISO 형식) - target_age와 둘 중 하나 필수 예시: |
direction_method | string | 선택 | 디렉션 방법 (ptolemy/placidus/regiomontanus/naibod) 예시: 기본값: |
direction_type | string | 선택 | 디렉션 타입 (direct/converse/both) 예시: 기본값: |
key_rate | number | 선택 | 1년당 디렉션 키 비율 (보통 1도/년, 0.8 ~ 1.2) 예시: 기본값: |
house_system | string | 선택 | 하우스 시스템 (PLACIDUS, WHOLE_SIGN, EQUAL 등) 예시: 기본값: |
include_aspects | boolean | 선택 | 디렉션 애스펙트 포함 여부 예시: 기본값: |
orb_degrees | number | 선택 | 애스펙트 오브 허용 범위 (0.5 ~ 5.0도, 디렉션은 보통 좁게) 예시: 기본값: |
include_mc_asc | boolean | 선택 | MC/ASC 디렉션 포함 여부 예시: 기본값: |
name | string | 선택 | 차트 소유자 이름 예시: |
target_age vs target_date
target_age와 target_date 중 하나는 반드시 제공해야 합니다. target_age를 사용하면 소수점으로 정확한 나이를 지정할 수 있습니다 (예: 25.5 = 25세 6개월). target_date를 제공하면 시스템이 자동으로 나이를 계산합니다.
요청 예시
curl -X POST https://api.destinyapi.com/v1/astrology/directions \
-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
},
"target_age": 35,
"direction_method": "ptolemy",
"direction_type": "direct",
"key_rate": 1,
"house_system": "PLACIDUS",
"include_aspects": true,
"orb_degrees": 1,
"include_mc_asc": true,
"name": "John Doe"
}'출생 시간 정확성
프라이머리 디렉션은 출생 시간에 매우 민감합니다. 출생 시간이 4분 차이 나면 약 1년의 타이밍 오차가 발생할 수 있습니다. 가능한 한 정확한 출생 시간을 사용하는 것이 중요합니다.
응답 구조
성공 응답 (200)
성공 응답
응답 필드 설명
- natal_chart: 출생 차트 기본 정보
chart_info: 차트 메타데이터 (name, datetime, location, house_system, timezone)angles: 앵글 정보 (ascendant, midheaven)bodies: 네이탈 행성 위치 (longitude, latitude, distance, sign, house, retrograde, dms, speed)houses: 네이탈 하우스 정보 (house_1 ~ house_12 형식, cusp_longitude, sign, bodies 배열)aspects: 네이탈 애스펙트 (aspect_type은 Title Case: Trine, Conjunction 등)dignities: 디그니티 정보
- direction_info: 디렉션 계산 정보
method: 디렉션 계산 방법 (ptolemy, placidus, regiomontanus, naibod)direction_type: 디렉션 타입 (direct/converse/both)age: 대상 나이natal_date: 출생 날짜calculation_date: 계산 수행 시간arc_per_year: 연간 아크 비율 (key_rate, 보통 1.0)
- directed_points: 디렉션된 천체 위치
- 각 천체별 객체 (sun, moon, mercury, venus, mars, ascendant, midheaven 등):
natal_longitude: 네이탈 황경 (0-360도)directed_longitude: 디렉션된 황경 (네이탈 위치 + arc)arc: 이동한 아크 (보통 나이 × key_rate)sign: 디렉션된 별자리
- 각 천체별 객체 (sun, moon, mercury, venus, mars, ascendant, midheaven 등):
- active_directions: 활성 디렉션 애스펙트
- 디렉션된 포인트가 네이탈 포인트와 이루는 애스펙트 목록:
directed_point: 디렉션된 천체/포인트 ID (소문자)natal_point: 네이탈 천체/포인트 ID (소문자)aspect_type: 애스펙트 유형 (소문자: conjunction, sextile, square, trine, opposition)arc: 디렉션 아크orb: 정확한 각도와의 차이
- 디렉션된 포인트가 네이탈 포인트와 이루는 애스펙트 목록:
- timestamp: 응답 생성 시간 (ISO 8601 형식)
- usage_info: API 사용량 정보
중요한 프라이머리 디렉션
| 디렉션 | 의미 | 타이밍 정확도 |
|---|---|---|
| Directed Sun ☌ Natal Venus | 사랑, 결혼, 창조적 성취의 중요한 해 | ±6개월 |
| Directed Ascendant ☌ Natal Jupiter | 성장, 확장, 행운의 시기 | ±6개월 |
| Directed MC ☌ Natal Sun | 경력의 정점, 공적 인정 | ±6개월 |
| Directed Moon □ Natal Saturn | 감정적 시련, 책임 증가 | ±6개월 |
| Directed Mars ☍ Natal Mars | 갈등, 에너지 폭발, 행동의 전환점 | ±6개월 |
디렉션 해석의 핵심 원칙
1. 정확성이 생명: 출생 시간 4분 = 약 1년의 타이밍 차이
2. 오브는 좁게: 보통 1도 이내만 유효 (진행과 다름)
3. 앵글 디렉션 중요: ASC/MC의 디렉션이 특히 강력
4. 외부 사건: 2차 진행(내면)과 달리 외부 사건 예측에 탁월
5. 트랜짓 확인: 디렉션+트랜짓이 함께 작용할 때 사건 발생 가능성 최고
에러 응답
잘못된 날짜 형식 (400)
날짜 형식 오류
{
"success": false,
"error": "Invalid value for 'body -> natal_datetime': Invalid datetime format. Use ISO format: YYYY-MM-DDTHH:MM:SS",
"error_code": 400,
"details": null,
"timestamp": "2024-07-17T12:00:00.123456"
}대상 연령/날짜 누락 (400)
필수 파라미터 누락
{
"success": false,
"error": "Invalid request data: Either 'target_age' or 'target_date' must be provided",
"error_code": 400,
"details": null,
"timestamp": "2024-07-17T12:00:00.123456"
}잘못된 오브 범위 (400)
오브 범위 오류
{
"success": false,
"error": "Invalid value for 'body -> orb_degrees': ensure this value is less than or equal to 5.0",
"error_code": 400,
"details": null,
"timestamp": "2024-07-17T12:00:00.123456"
}사용량 제한 초과 (429)
Rate Limit 초과
{
"success": false,
"error": "Rate limit exceeded for feature: directions",
"error_code": 429,
"details": null,
"timestamp": "2024-07-17T12:00:00.123456"
}에러 코드 요약
| 코드 | 설명 | 해결 방법 |
|---|---|---|
| 400 | 잘못된 요청 데이터 | 날짜 형식, target_age/target_date 제공, 좌표 범위, 오브 범위 확인 |
| 401 | 인증 실패 | 유효한 API 키를 X-API-Key 헤더에 포함 |
| 403 | 권한 없음 | 현재 플랜에서 directions 기능 사용 가능 여부 확인 |
| 429 | 사용량 제한 초과 | 플랜 업그레이드 또는 다음 주기까지 대기 |
| 500 | 서버 내부 오류 | 잠시 후 재시도, 지속 시 고객 지원 문의 |
사용 예시
인생의 주요 전환점 찾기
25세부터 35세까지 각 나이별로 디렉션을 계산하여 디렉션된 태양, 달, ASC가 네이탈 차트의 중요 포인트(태양, 달, 금성, 목성, ASC, MC)와 합, 사각, 삼각, 대칭을 이루는 시기를 찾아냅니다. 이 시기들이 인생의 주요 사건이 일어날 가능성이 높은 해입니다.
결혼 시기 예측 (고전 기법)
다음 디렉션 중 하나가 활성화되는 해에 결혼 가능성이 높습니다:
- Directed ASC ☌ Natal Venus (상대방과의 만남)
- Directed Venus ☌ Natal ASC (사랑의 표현)
- Directed Sun ☌ Natal Venus (공식적 결합)
- Directed Moon ☌ Natal Venus (감정적 유대)
경력 발전 시기
다음 디렉션이 활성화될 때 경력에서 중요한 발전이 있을 수 있습니다:
- Directed MC ☌ Natal Sun (공적 인정의 정점)
- Directed MC ☌ Natal Jupiter (확장, 승진)
- Directed Sun ☌ Natal MC (리더십 획득)
- Directed ASC △ Natal Saturn (책임과 권위 증가)
관련 엔드포인트
- Natal Chart API - 출생 차트 계산
- Progressions API - 2차 진행 차트
- Transits API - 트랜짓 차트
- Solar Returns API - 솔라 리턴
고전 점성술의 정수
프라이머리 디렉션은 고대 바빌로니아부터 중세 아랍 점성술, 르네상스 유럽 점성술에 이르기까지 가장 신뢰받았던 예측 기법입니다. 월리엄 릴리(William Lilly)는 "정확한 출생 시간만 있다면 프라이머리 디렉션만큼 확실한 예측 도구는 없다"고 했습니다. 현대에 와서는 계산의 복잡성 때문에 2차 진행과 트랜짓에 밀렸지만, 컴퓨터 시대에 다시 그 가치를 인정받고 있습니다.