Transits API
트랜짓(Transits)은 현재 하늘의 행성들이 출생 차트의 행성들과 이루는 애스펙트를 분석하여 현재 또는 특정 시점의 점성술적 영향을 파악합니다. 행운의 시기, 도전의 시기, 그리고 중요한 인생 전환점을 예측하는 데 가장 널리 사용되는 기법입니다.
트랜짓 계산
/v1/astrology/transitsPredictive특정 시점의 트랜짓 행성 위치와 네이탈 차트와의 애스펙트를 계산합니다.
트랜짓이란?
트랜짓은 현재 하늘을 지나가는 행성들의 위치를 출생 차트의 고정된 행성 위치와 비교하여 분석합니다. 트랜짓 행성이 네이탈 행성과 이루는 각도(애스펙트)에 따라 특정 삶의 영역에서 활성화, 도전, 또는 기회가 발생합니다.
- Transit Planets: 특정 시점의 실제 행성 위치 (하늘의 현재 상태)
- Natal Planets: 출생 시 고정된 행성 위치 (개인의 출생 차트)
- Transit Aspects: 트랜짓 행성이 네이탈 행성과 이루는 각도 관계 (합, 대립, 삼분, 사분 등)
주요 트랜짓 행성의 영향
| 행성 | 주기 | 영향 특성 |
|---|---|---|
| Moon | ~2.5일 | 감정, 기분, 일상의 변화 (매우 빠르고 일시적) |
| Mercury | ~20일 | 의사소통, 사고, 단기 결정 |
| Venus | ~23일 | 관계, 사랑, 가치, 재정 |
| Sun | ~30일 | 활력, 자아 표현, 목표 달성 |
| Mars | ~40일 | 에너지, 행동, 갈등, 추진력 |
| Jupiter | ~13개월 | 확장, 행운, 성장, 기회 (중요한 긍정적 시기) |
| Saturn | ~2.5년 | 책임, 제약, 시련, 성숙 (인생의 전환점) |
| Uranus | ~7년 | 갑작스런 변화, 혁신, 자유 (예상치 못한 사건) |
| Neptune | ~14년 | 환상, 영성, 혼란, 창의성 (장기적 영적 변화) |
| Pluto | ~20년 | 변혁, 권력, 재생, 심오한 변화 (삶의 근본적 재구성) |
요청 파라미터
파라미터
| 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|
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) - 미제공 시 좌표로 자동 감지 예시: |
transit_datetime | string | 필수 | 트랜짓 시점의 날짜 및 시간 (ISO 8601 형식) 예시: |
transit_location | object | 선택 | 트랜짓 계산 위치 (기본값: 출생 위치 사용) |
transit_location.latitude | number | 선택 | 위도 (-90 ~ 90) 예시: |
transit_location.longitude | number | 선택 | 경도 (-180 ~ 180) 예시: |
transit_location.timezone | string | 선택 | IANA 타임존 예시: |
house_system | string | 선택 | 하우스 시스템 (PLACIDUS, WHOLE_SIGN, EQUAL 등) 예시: 기본값: |
orb_degrees | number | 선택 | 애스펙트 오브 허용 범위 (0.5 ~ 10.0도) 예시: 기본값: |
name | string | 선택 | 차트 소유자 이름 예시: |
요청 예시
curl -X POST https://api.destinyapi.com/v1/astrology/transits \
-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
},
"transit_datetime": "2025-01-15T12:00:00",
"transit_location": {
"latitude": 37.5665,
"longitude": 126.978,
"timezone": "Asia/Seoul",
"elevation": 38
},
"house_system": "PLACIDUS",
"orb_degrees": 2,
"name": "John Doe"
}'타임존 자동 감지
natal_location.timezone을 제공하지 않으면 위도/경도 좌표를 기반으로 자동으로 타임존이 감지됩니다. 정확한 출생 시간대를 알고 있다면 명시적으로 제공하는 것을 권장합니다.
하우스 시스템
지원되는 하우스 시스템:
| 시스템 | 설명 |
|---|---|
PLACIDUS | 가장 널리 사용되는 시간 기반 시스템 (기본값) |
WHOLE_SIGN | 헬레니즘 점성술의 전통 시스템 |
EQUAL | ASC에서 30도씩 균등 분할 |
KOCH | Koch 하우스 시스템 |
CAMPANUS | Campanus 하우스 시스템 |
응답 구조
성공 응답 (200)
성공 응답
응답 필드 설명
- natal_chart_metadata: 출생 차트 메타데이터
calculation_type: 계산 유형 ("NatalChart" 고정값)datetime_utc: 출생 시간 (UTC)datetime_local: 출생 시간 (현지)timezone_str: 타임존latitude,longitude: 출생 위치 좌표house_system: 사용된 하우스 시스템ephemeris_file: 사용된 천문력 파일 ("de440.bsp" 고정값)
- transit_chart_metadata: 트랜짓 시점 메타데이터
calculation_type: "TransitChart" (고정값)datetime_utc: 트랜짓 시간 (UTC)datetime_local: 트랜짓 시간 (UTC로 동일하게 반환됨)- 기타 필드는 natal_chart_metadata와 동일
- natal_celestial_bodies: 출생 차트의 행성 위치 목록
id: 천체 식별자 (소문자, 예: sun, moon, mercury)name: 천체 이름 (예: Sun, Moon, Mercury)type: 천체 유형 (Planet, Node, Angle 등 - PascalCase)longitude_decimal: 황경 (0-360도)latitude_decimal: 황위longitude_speed_decimal_per_day: 황경 일일 이동 속도latitude_speed_decimal_per_day: 황위 일일 이동 속도distance_au: 지구로부터의 거리 (천문단위)declination_decimal: 적위is_retrograde: 역행 여부sign_name: 위치한 별자리sign_degree_decimal: 별자리 내 위치 (0-30도)sign_longitude_dms: DMS 형식 (예: "23° Gemini 27' 24"")house_number: 하우스 번호 (1-12)ra_hours: 적경 (시간 단위)
- transit_celestial_bodies: 트랜짓 시점의 행성 위치 목록
- 포함 필드:
id,name,type,longitude_decimal,latitude_decimal,longitude_speed_decimal_per_day,declination_decimal,is_retrograde - 미구현 필드 (현재 버전에서는 빈 값 또는 0으로 반환):
sign_name: 빈 문자열 ("")sign_degree_decimal: 0.0latitude_speed_decimal_per_day: nulldistance_au: nullsign_longitude_dms: nullhouse_number: nullra_hours: null
- 참고: 트랜짓 천체는 별자리 계산이 필요한 경우
longitude_decimal값을 직접 사용하여 클라이언트 측에서 계산할 수 있습니다 (longitude ÷ 30 = 별자리 인덱스, longitude % 30 = 별자리 내 도수).
- 포함 필드:
- transit_aspects: 트랜짓 애스펙트 목록
body1_id: 트랜짓 행성 ID (소문자, 예: sun, saturn, neptune)body2_id: 네이탈 행성 ID (소문자, 예: sun, mars, venus)aspect_type: 애스펙트 유형 (conjunction, opposition, trine, square, sextile 등)orb_decimal: 정확한 각도와의 차이 (오브)delta_decimal: 두 천체 사이의 실제 각도is_applying: 접근 중 (애스펙트가 강화되는 중)is_separating: 분리 중 (애스펙트가 약화되는 중)is_exact: 정확한 각도 여부
- timestamp: 응답 생성 시간 (ISO 8601 형식)
- usage_info: API 사용량 정보
애스펙트 유형
| 애스펙트 | 각도 | 성질 | 의미 |
|---|---|---|---|
conjunction | 0° | 중립/강력 | 융합, 시작, 강렬한 에너지 집중 |
opposition | 180° | 긴장 | 대립, 균형 필요, 타협, 완성 |
trine | 120° | 조화 | 흐름, 행운, 자연스러운 재능 발휘 |
square | 90° | 긴장 | 도전, 갈등, 성장을 위한 압박 |
sextile | 60° | 조화 | 기회, 협력, 의식적 노력으로 활용 가능 |
quincunx | 150° | 긴장 | 조정, 불편함, 적응 필요 |
애스펙트 해석 팁
is_applying이 true인 애스펙트는 아직 영향력이 강화되는 중이므로 앞으로 더 강력해집니다. is_separating이 true인 경우 영향력이 감소하는 중입니다. 오브(orb_decimal)가 작을수록 영향이 강력하며, 1도 이하일 때 가장 중요합니다.
참고: body1_id와 body2_id는 모두 소문자로 반환됩니다 (예: sun, moon, saturn). 두 ID를 구분하려면 transit_celestial_bodies와 natal_celestial_bodies 배열에서 각각 찾아야 합니다.
에러 응답
잘못된 날짜 형식 (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 value for 'body -> orb_degrees': ensure this value is less than or equal to 10.0",
"error_code": 400,
"details": null,
"timestamp": "2024-07-17T12:00:00.123456"
}필수 필드 누락 (400)
필수 필드 누락
{
"success": false,
"error": "Invalid value for 'body -> natal_datetime': field required",
"error_code": 400,
"details": null,
"timestamp": "2024-07-17T12:00:00.123456"
}사용량 제한 초과 (429)
Rate Limit 초과
{
"success": false,
"error": "Rate limit exceeded for feature: transits",
"error_code": 429,
"details": null,
"timestamp": "2024-07-17T12:00:00.123456"
}에러 코드 요약
| 코드 | 설명 | 해결 방법 |
|---|---|---|
| 400 | 잘못된 요청 데이터 | 날짜 형식(ISO 8601), 좌표 범위, 오브 범위 확인 |
| 401 | 인증 실패 | 유효한 API 키를 X-API-Key 헤더에 포함 |
| 403 | 권한 없음 | 현재 플랜에서 transits 기능 사용 가능 여부 확인 |
| 429 | 사용량 제한 초과 | 플랜 업그레이드 또는 다음 주기까지 대기 |
| 500 | 서버 내부 오류 | 잠시 후 재시도, 지속 시 고객 지원 문의 |
사용 예시
중요한 토성 트랜짓 찾기
토성이 네이탈 태양에 스퀘어를 이룰 때 (Saturn Square Sun): 인생의 중요한 책임과 시련의 시기. 일반적으로 2.5년마다 발생하며 자아 정체성과 목표에 대한 재평가를 요구합니다.
목성의 행운 주기
목성이 네이탈 금성에 트라인을 이룰 때 (Jupiter Trine Venus): 관계, 재정, 즐거움의 확장 시기. 연애, 결혼, 재정적 행운의 좋은 타이밍입니다.
외행성 트랜짓의 중요성
천왕성, 해왕성, 명왕성의 트랜짓은 매우 느리게 진행되므로 (수년 단위), 이들이 네이탈 개인 행성(태양, 달, 수성, 금성, 화성)과 애스펙트를 이룰 때는 인생의 중대한 전환점으로 작용합니다.
관련 엔드포인트
- Natal Chart API - 출생 차트 계산
- Progressions API - 프로그레션 차트 계산
- Solar Returns API - 솔라 리턴 차트 계산
실전 활용 팁
트랜짓 분석 시 다음 순서로 접근하세요:
1. 외행성 트랜짓 (토성, 천왕성, 해왕성, 명왕성) - 장기적 주요 테마
2. 목성 트랜짓 - 기회와 확장의 시기
3. 개인 행성 트랜짓 (태양, 화성, 금성) - 단기적 영향
트랜짓은 Annual Profections, Solar Returns와 함께 사용할 때 가장 강력한 예측 도구가 됩니다.