첫 번째 요청
이 가이드에서는 Destiny Engine API로 첫 번째 출생 차트를 계산하는 방법을 알아봅니다. 약 5분이면 완료할 수 있습니다.
준비사항
API 키
아직 API 키가 없다면 인증 가이드를 참고하여 발급받으세요.
API 엔드포인트
기본 URL: https://api.destinyapi.com
출생 차트 계산하기
가장 기본적인 API 호출은 출생 차트 계산입니다. /v1/astrology/natal-chart 엔드포인트에 출생 정보를 POST 요청으로 전송하면 됩니다.
요청 예제
다음은 1990년 1월 15일 14:30, 서울에서 태어난 사람의 출생 차트를 계산하는 예제입니다:
curl -X POST https://api.destinyapi.com/v1/astrology/natal-chart \
-H "X-API-Key: your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"datetime": "1990-01-15T14:30:00",
"location": {
"latitude": 37.5665,
"longitude": 126.978,
"timezone": "Asia/Seoul",
"elevation": 38
},
"house_system": "PLACIDUS",
"name": "John Doe",
"include_asteroids": false
}'필수 파라미터
| 파라미터 | 타입 | 설명 | 예시 |
|---|---|---|---|
date | string | 출생 날짜 (YYYY-MM-DD) | "1990-01-15" |
time | string | 출생 시간 (HH:MM) | "14:30" |
lat | number | 출생 위도 | 37.5665 |
lon | number | 출생 경도 | 126.9780 |
tz | string | 타임존 (IANA 형식) | "Asia/Seoul" |
타임존 주의사항
정확한 차트 계산을 위해서는 올바른 타임존을 지정해야 합니다. 한국은 Asia/Seoul, 미국 뉴욕은 America/New_York을 사용합니다.
응답 확인하기
요청이 성공하면 다음과 같은 JSON 응답을 받게 됩니다:
{
"success": true,
"data": {
"chart_info": {
"name": "John Doe",
"datetime": "1990-01-15T14:30:00",
"location": {
"latitude": 37.5665,
"longitude": 126.978,
"elevation": 38
},
"house_system": "PLACIDUS",
"timezone": "Asia/Seoul"
},
"angles": {
"asc": {
"longitude": 73.80217769863685,
"sign": "Gemini",
"dms": "13° Gemini 48' 07\""
},
"mc": {
"longitude": 321.51259762720684,
"sign": "Aquarius",
"dms": "21° Aquarius 30' 45\""
}
},
"bodies": {
"moon": {
"longitude": 164.10728449894503,
"latitude": -2.433219801367135,
"distance": 0.0026239507561749147,
"sign": "Virgo",
"house": 4,
"retrograde": false,
"dms": "14° Virgo 06' 25\"",
"speed": 12.572773570309437
},
"pluto": {
"longitude": 227.42263468468818,
"latitude": 15.37669864517166,
"distance": 30.007005739975973,
"sign": "Scorpio",
"house": 6,
"retrograde": false,
"dms": "17° Scorpio 25' 20\"",
"speed": 0.020466473597480217
},
"mercury": {
"longitude": 281.5452507322837,
"latitude": 3.37829136814258,
"distance": 0.7050147477210029,
"sign": "Capricorn",
"house": 8,
"retrograde": true,
"dms": "11° Capricorn 32' 41\"",
"speed": -0.7633419239937211
},
"mars": {
"longitude": 259.71630173185815,
"latitude": -0.18890186715558102,
"distance": 2.2263250385699975,
"sign": "Sagittarius",
"house": 7,
"retrograde": false,
"dms": "19° Sagittarius 42' 58\"",
"speed": 0.7117844995264022
},
"sun": {
"longitude": 294.8024863243448,
"latitude": -0.00008908560370540947,
"distance": 0.9836363353585106,
"sign": "Capricorn",
"house": 8,
"retrograde": false,
"dms": "24° Capricorn 48' 08\"",
"speed": 1.0182543072914996
},
"uranus": {
"longitude": 276.59757302053856,
"latitude": -0.2726160945577932,
"distance": 20.314516054119306,
"sign": "Capricorn",
"house": 8,
"retrograde": false,
"dms": "06° Capricorn 35' 51\"",
"speed": 0.057876678783941315
},
"neptune": {
"longitude": 282.5556941535978,
"latitude": 0.8457625771169008,
"distance": 31.170544300803186,
"sign": "Capricorn",
"house": 8,
"retrograde": false,
"dms": "12° Capricorn 33' 20\"",
"speed": 0.03720272361533716
},
"saturn": {
"longitude": 287.28256992260805,
"latitude": 0.2771488150757121,
"distance": 11.000447376290355,
"sign": "Capricorn",
"house": 8,
"retrograde": false,
"dms": "17° Capricorn 16' 56\"",
"speed": 0.11785094930019113
},
"venus": {
"longitude": 300.84613239834005,
"latitude": 5.345328409295521,
"distance": 0.2685803172382466,
"sign": "Aquarius",
"house": 9,
"retrograde": true,
"dms": "00° Aquarius 50' 45\"",
"speed": -0.5903041354031302
},
"jupiter": {
"longitude": 93.39789745021899,
"latitude": -0.08336863355896541,
"distance": 4.22763815782696,
"sign": "Cancer",
"house": 1,
"retrograde": true,
"dms": "03° Cancer 23' 52\"",
"speed": -0.11775938785376638
},
"true_node": {
"longitude": 317.7080946575413,
"latitude": 0,
"distance": null,
"sign": "Aquarius",
"house": 9,
"retrograde": true,
"dms": "17° Aquarius 42' 28\"",
"speed": -0.05294114231446656
}
},
"houses": {
"house_1": {
"cusp_longitude": 73.80217763515988,
"sign": "Gemini",
"bodies": [
"jupiter",
"asc"
]
},
"house_2": {
"cusp_longitude": 96.2296514991633,
"sign": "Cancer",
"bodies": []
},
"house_3": {
"cusp_longitude": 117.44718533695762,
"sign": "Cancer",
"bodies": []
},
"house_4": {
"cusp_longitude": 141.5125975648466,
"sign": "Leo",
"bodies": [
"moon"
]
},
"house_5": {
"cusp_longitude": 172.51731593092222,
"sign": "Virgo",
"bodies": []
},
"house_6": {
"cusp_longitude": 212.55778173740327,
"sign": "Scorpio",
"bodies": [
"pluto"
]
},
"house_7": {
"cusp_longitude": 253.80217763515986,
"sign": "Sagittarius",
"bodies": [
"mars"
]
},
"house_8": {
"cusp_longitude": 276.2296514991633,
"sign": "Capricorn",
"bodies": [
"mercury",
"sun",
"uranus",
"neptune",
"saturn"
]
},
"house_9": {
"cusp_longitude": 297.4471853369576,
"sign": "Capricorn",
"bodies": [
"venus",
"true_node"
]
},
"house_10": {
"cusp_longitude": 321.5125975648466,
"sign": "Aquarius",
"bodies": [
"mc"
]
},
"house_11": {
"cusp_longitude": 352.5173159309222,
"sign": "Pisces",
"bodies": []
},
"house_12": {
"cusp_longitude": 32.557781737403275,
"sign": "Taurus",
"bodies": []
}
},
"aspects": [
{
"body1": "asc",
"body2": "mc",
"aspect_type": "Trine",
"orb": 8,
"exact": false,
"applying": null
},
{
"body1": "jupiter",
"body2": "true_node",
"aspect_type": "Sesquiquadrate",
"orb": 2.5,
"exact": false,
"applying": false
},
{
"body1": "mars",
"body2": "asc",
"aspect_type": "Opposition",
"orb": 8,
"exact": false,
"applying": null
},
{
"body1": "mars",
"body2": "mc",
"aspect_type": "Sextile",
"orb": 6,
"exact": false,
"applying": null
},
{
"body1": "mars",
"body2": "true_node",
"aspect_type": "Sextile",
"orb": 6,
"exact": false,
"applying": true
},
{
"body1": "mercury",
"body2": "asc",
"aspect_type": "Quincunx",
"orb": 3,
"exact": false,
"applying": null
},
{
"body1": "mercury",
"body2": "neptune",
"aspect_type": "Conjunction",
"orb": 8,
"exact": false,
"applying": true
},
{
"body1": "mercury",
"body2": "saturn",
"aspect_type": "Conjunction",
"orb": 8,
"exact": false,
"applying": true
},
{
"body1": "mercury",
"body2": "uranus",
"aspect_type": "Conjunction",
"orb": 8,
"exact": false,
"applying": false
},
{
"body1": "moon",
"body2": "asc",
"aspect_type": "Square",
"orb": 8,
"exact": false,
"applying": null
},
{
"body1": "moon",
"body2": "jupiter",
"aspect_type": "Quintile",
"orb": 1.5,
"exact": false,
"applying": false
},
{
"body1": "moon",
"body2": "mars",
"aspect_type": "Square",
"orb": 8,
"exact": false,
"applying": false
},
{
"body1": "moon",
"body2": "mercury",
"aspect_type": "Trine",
"orb": 9,
"exact": false,
"applying": true
},
{
"body1": "moon",
"body2": "neptune",
"aspect_type": "Trine",
"orb": 9,
"exact": false,
"applying": true
},
{
"body1": "moon",
"body2": "pluto",
"aspect_type": "Sextile",
"orb": 7,
"exact": false,
"applying": false
},
{
"body1": "moon",
"body2": "saturn",
"aspect_type": "Trine",
"orb": 9,
"exact": false,
"applying": false
},
{
"body1": "moon",
"body2": "uranus",
"aspect_type": "Trine",
"orb": 9,
"exact": false,
"applying": true
},
{
"body1": "moon",
"body2": "venus",
"aspect_type": "Sesquiquadrate",
"orb": 2.5,
"exact": false,
"applying": false
},
{
"body1": "neptune",
"body2": "asc",
"aspect_type": "Quincunx",
"orb": 3,
"exact": false,
"applying": null
},
{
"body1": "neptune",
"body2": "saturn",
"aspect_type": "Conjunction",
"orb": 8,
"exact": false,
"applying": true
},
{
"body1": "pluto",
"body2": "jupiter",
"aspect_type": "Sesquiquadrate",
"orb": 2.5,
"exact": false,
"applying": false
},
{
"body1": "pluto",
"body2": "mc",
"aspect_type": "Square",
"orb": 7,
"exact": false,
"applying": null
},
{
"body1": "pluto",
"body2": "mercury",
"aspect_type": "Sextile",
"orb": 6,
"exact": false,
"applying": true
},
{
"body1": "pluto",
"body2": "neptune",
"aspect_type": "Sextile",
"orb": 6,
"exact": false,
"applying": false
},
{
"body1": "pluto",
"body2": "saturn",
"aspect_type": "Sextile",
"orb": 6,
"exact": false,
"applying": false
},
{
"body1": "pluto",
"body2": "true_node",
"aspect_type": "Square",
"orb": 7,
"exact": false,
"applying": false
},
{
"body1": "pluto",
"body2": "venus",
"aspect_type": "Quintile",
"orb": 1.5,
"exact": false,
"applying": false
},
{
"body1": "saturn",
"body2": "true_node",
"aspect_type": "Semisextile",
"orb": 2,
"exact": false,
"applying": false
},
{
"body1": "sun",
"body2": "saturn",
"aspect_type": "Conjunction",
"orb": 10,
"exact": false,
"applying": true
},
{
"body1": "sun",
"body2": "venus",
"aspect_type": "Conjunction",
"orb": 10,
"exact": false,
"applying": false
},
{
"body1": "true_node",
"body2": "asc",
"aspect_type": "Trine",
"orb": 8,
"exact": false,
"applying": null
},
{
"body1": "true_node",
"body2": "mc",
"aspect_type": "Conjunction",
"orb": 8,
"exact": false,
"applying": null
},
{
"body1": "uranus",
"body2": "jupiter",
"aspect_type": "Opposition",
"orb": 8,
"exact": false,
"applying": true
},
{
"body1": "uranus",
"body2": "mc",
"aspect_type": "Semisquare",
"orb": 2.5,
"exact": false,
"applying": null
},
{
"body1": "uranus",
"body2": "neptune",
"aspect_type": "Conjunction",
"orb": 8,
"exact": false,
"applying": false
},
{
"body1": "venus",
"body2": "asc",
"aspect_type": "Sesquiquadrate",
"orb": 2.5,
"exact": false,
"applying": null
},
{
"body1": "venus",
"body2": "jupiter",
"aspect_type": "Quincunx",
"orb": 3,
"exact": false,
"applying": true
},
{
"body1": "jupiter",
"body2": "asc",
"aspect_type": "Parallel",
"orb": 1,
"exact": false,
"applying": null
},
{
"body1": "mars",
"body2": "asc",
"aspect_type": "Contra-Parallel",
"orb": 1,
"exact": false,
"applying": null
},
{
"body1": "mars",
"body2": "jupiter",
"aspect_type": "Contra-Parallel",
"orb": 1,
"exact": false,
"applying": null
},
{
"body1": "mars",
"body2": "uranus",
"aspect_type": "Parallel",
"orb": 1,
"exact": false,
"applying": null
},
{
"body1": "neptune",
"body2": "asc",
"aspect_type": "Contra-Parallel",
"orb": 1,
"exact": false,
"applying": null
},
{
"body1": "neptune",
"body2": "saturn",
"aspect_type": "Parallel",
"orb": 1,
"exact": true,
"applying": null
},
{
"body1": "saturn",
"body2": "asc",
"aspect_type": "Contra-Parallel",
"orb": 1,
"exact": false,
"applying": null
},
{
"body1": "sun",
"body2": "asc",
"aspect_type": "Contra-Parallel",
"orb": 1.5,
"exact": false,
"applying": null
},
{
"body1": "sun",
"body2": "neptune",
"aspect_type": "Parallel",
"orb": 1.5,
"exact": false,
"applying": null
},
{
"body1": "sun",
"body2": "saturn",
"aspect_type": "Parallel",
"orb": 1.5,
"exact": false,
"applying": null
},
{
"body1": "uranus",
"body2": "jupiter",
"aspect_type": "Contra-Parallel",
"orb": 1,
"exact": false,
"applying": null
},
{
"body1": "venus",
"body2": "mc",
"aspect_type": "Parallel",
"orb": 1,
"exact": false,
"applying": null
},
{
"body1": "venus",
"body2": "true_node",
"aspect_type": "Parallel",
"orb": 1,
"exact": false,
"applying": null
}
],
"dignities": {
"moon": {
"essential_dignities": {
"rulership": null,
"exaltation": null,
"triplicity": "Moon",
"term": null,
"face": null,
"detriment": null,
"fall": null
},
"is_peregrine": false,
"lilly_score": 3
},
"mercury": {
"essential_dignities": {
"rulership": null,
"exaltation": null,
"triplicity": null,
"term": null,
"face": null,
"detriment": null,
"fall": null
},
"is_peregrine": true,
"lilly_score": 0
},
"mars": {
"essential_dignities": {
"rulership": null,
"exaltation": null,
"triplicity": null,
"term": null,
"face": null,
"detriment": null,
"fall": null
},
"is_peregrine": true,
"lilly_score": 0
},
"sun": {
"essential_dignities": {
"rulership": null,
"exaltation": null,
"triplicity": null,
"term": null,
"face": "Sun",
"detriment": null,
"fall": null
},
"is_peregrine": false,
"lilly_score": 1
},
"saturn": {
"essential_dignities": {
"rulership": "Saturn",
"exaltation": null,
"triplicity": null,
"term": null,
"face": null,
"detriment": null,
"fall": null
},
"is_peregrine": false,
"lilly_score": 5
},
"venus": {
"essential_dignities": {
"rulership": null,
"exaltation": null,
"triplicity": null,
"term": null,
"face": "Venus",
"detriment": null,
"fall": null
},
"is_peregrine": false,
"lilly_score": 1
},
"jupiter": {
"essential_dignities": {
"rulership": null,
"exaltation": "Jupiter",
"triplicity": null,
"term": null,
"face": null,
"detriment": null,
"fall": null
},
"is_peregrine": false,
"lilly_score": 4
}
}
},
"message": "Natal chart calculated successfully",
"timestamp": "2025-11-12T03:59:42.782002",
"usage_info": {
"feature": "natal_chart",
"user": "internal",
"used": 0,
"limit": 999999,
"remaining": 999999
}
}응답 구조
success: 요청 성공 여부 (boolean)data: 차트 계산 결과planets: 각 행성의 위치, 별자리, 하우스 정보houses: 12하우스 정보aspects: 행성 간 애스펙트 (각도 관계)
metadata: 요청에 사용된 메타데이터
에러 처리
API 호출이 실패하면 다음과 같은 에러 응답을 받게 됩니다:
{
"success": false,
"error": "Invalid date format. Expected YYYY-MM-DD."
}또는 FastAPI 기본 포맷:
{
"detail": "Invalid date format. Expected YYYY-MM-DD."
}일반적인 에러 코드:
| 에러 코드 | 설명 | 해결 방법 |
|---|---|---|
INVALID_DATE | 날짜 형식이 잘못됨 | YYYY-MM-DD 형식으로 입력 |
INVALID_TIME | 시간 형식이 잘못됨 | HH:MM 형식으로 입력 (24시간제) |
INVALID_COORDINATES | 위도/경도 범위 초과 | 위도: -90~90, 경도: -180~180 |
INVALID_TIMEZONE | 잘못된 타임존 | IANA 타임존 데이터베이스 참고 |
다음 단계
축하합니다! 첫 번째 API 요청을 성공적으로 완료했습니다. 이제 다음 단계로 진행해보세요: