DESTINYAPI · Developer Portal

Firdaria API

Firdaria는 페르시아/아랍 전통 점성술의 행성 주기 체계입니다. 인생을 7개의 주요 행성 주기로 나누며, 각 주기는 해당 행성의 상징적 의미가 강조되는 시기입니다. 성별에 따라 서로 다른 행성 순서를 사용합니다.

Firdaria 계산

POST/v1/astrology/firdariaClassical

현재 나이와 성별에 따른 Firdaria 행성 주기를 계산합니다.

Firdaria란?

Firdaria는 출생부터 시작하여 75년 주기로 구성된 행성 시간 체계입니다. 각 행성은 특정 기간 동안 삶의 "지배자"(Time Lord) 역할을 하며, 그 기간 동안 해당 행성의 테마가 삶에서 두드러집니다.

  • Male (Diurnal) Sequence: 남성 또는 주간 출생의 경우 태양부터 시작하는 순서
  • Female (Nocturnal) Sequence: 여성 또는 야간 출생의 경우 달부터 시작하는 순서
  • 각 행성 주기는 7-14년 지속되며, 총 75년(남성) 또는 69년(여성) 주기로 구성

요청 파라미터

파라미터

이름타입필수설명
natal_datetimestring필수

출생 날짜 및 시간 (ISO 8601 형식)

예시: 1990-06-15T14:30:00

natal_locationobject필수

출생 위치 정보

natal_location.latitudenumber필수

위도 (-90 ~ 90)

예시: 37.5665

natal_location.longitudenumber필수

경도 (-180 ~ 180)

예시: 126.9780

natal_location.timezonestring선택

IANA 타임존 (예: Asia/Seoul) - 미제공 시 좌표로 자동 감지

예시: Asia/Seoul

current_ageinteger필수

현재 나이 (0-74세, Firdaria 주기 내)

예시: 35

genderstring필수

성별 (male, female, m, f 중 하나)

예시: male

namestring선택

차트 소유자 이름

예시: Sample User

나이 제한

Firdaria는 0-74세 범위 내에서 작동합니다. 75세 이상의 나이를 입력하면 400 에러가 반환됩니다. (여성 순서는 최대 69세까지)

요청 예시

curl -X POST https://api.destinyapi.com/v1/astrology/firdaria \
  -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,
  "gender": "male",
  "name": "John Doe"
}'

타임존 자동 감지

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

성별에 따른 행성 순서

Firdaria는 성별(또는 주야간)에 따라 다른 행성 순서를 사용합니다:

순서Male (Diurnal)기간Female (Nocturnal)기간
1Sun (태양)10년Moon (달)9년
2Venus (금성)8년Saturn (토성)14년
3Mercury (수성)14년Jupiter (목성)12년
4Moon (달)9년Mars (화성)7년
5Saturn (토성)14년Sun (태양)10년
6Jupiter (목성)12년Venus (금성)8년
7Mars (화성)7년Mercury (수성)14년
총 주기74년총 주기74년

행성별 주요 테마

행성주요 테마 및 상징
Sun (태양)권위, 정체성, 활력, 인정, 리더십, 자아실현
Moon (달)감정, 본능, 가정, 가족, 양육, 변화, 수용성
Mercury (수성)의사소통, 학습, 거래, 여행, 지적 활동, 다재다능함
Venus (금성)관계, 사랑, 아름다움, 예술, 조화, 즐거움, 가치
Mars (화성)행동, 용기, 갈등, 에너지, 주장, 욕망, 열정
Jupiter (목성)확장, 성장, 행운, 지혜, 철학, 관대함, 기회
Saturn (토성)구조, 훈련, 책임, 제한, 성숙, 인내, 업적

응답 구조

성공 응답 - Male (200)

남성 Firdaria 계산 결과

응답 상태:200
{
  "success": true,
  "data": {
    "firdaria_info": {
      "gender": "male",
      "current_age": 35,
      "sequence_type": "Male (Diurnal)",
      "calculation_date": "2025-11-12T03:59:43.875660"
    },
    "current_period": {
      "ruling_planet": "Moon",
      "start_age": 32,
      "end_age": 41,
      "duration_years": 9,
      "years_into_period": 3,
      "years_remaining": 6,
      "planet_themes": "Emotions, family, home, nurturing, public life, receptivity, fluctuation"
    },
    "all_periods": [
      {
        "planet": "Sun",
        "start_age": 0,
        "end_age": 10,
        "duration_years": 10,
        "is_current": false
      },
      {
        "planet": "Venus",
        "start_age": 10,
        "end_age": 18,
        "duration_years": 8,
        "is_current": false
      },
      {
        "planet": "Mercury",
        "start_age": 18,
        "end_age": 32,
        "duration_years": 14,
        "is_current": false
      },
      {
        "planet": "Moon",
        "start_age": 32,
        "end_age": 41,
        "duration_years": 9,
        "is_current": true
      },
      {
        "planet": "Saturn",
        "start_age": 41,
        "end_age": 55,
        "duration_years": 14,
        "is_current": false
      },
      {
        "planet": "Jupiter",
        "start_age": 55,
        "end_age": 67,
        "duration_years": 12,
        "is_current": false
      },
      {
        "planet": "Mars",
        "start_age": 67,
        "end_age": 74,
        "duration_years": 7,
        "is_current": false
      }
    ],
    "natal_info": {
      "name": "John Doe",
      "datetime": "1990-01-15T14:30:00",
      "location": {
        "latitude": 37.5665,
        "longitude": 126.978,
        "timezone": "Asia/Seoul"
      }
    },
    "interpretation": {
      "description": "At age 35, you are in the Moon period (years 32-41).",
      "current_focus": "This is a time when Moon's significations are emphasized in your life.",
      "note": "The condition of natal Moon in your birth chart colors how this period unfolds.",
      "period_progress": "3 out of 9 years complete"
    }
  },
  "message": "Firdaria calculated successfully",
  "timestamp": "2025-11-12T03:59:43.875667",
  "usage_info": {
    "feature": "firdaria",
    "user": "internal",
    "used": 0,
    "limit": 999999,
    "remaining": 999999
  }
}

성공 응답 - Female (200)

여성 Firdaria 계산 결과

응답 상태:200
{
  "success": true,
  "data": {
    "firdaria_info": {
      "gender": "female",
      "current_age": 28,
      "sequence_type": "Female (Nocturnal)",
      "calculation_date": "2025-10-30T17:30:00.123456"
    },
    "current_period": {
      "ruling_planet": "Mars",
      "start_age": 27,
      "end_age": 34,
      "duration_years": 7,
      "years_into_period": 1,
      "years_remaining": 6,
      "planet_themes": "Action, courage, conflict, energy, assertion, desire, passion"
    },
    "all_periods": [
      {
        "planet": "Moon",
        "start_age": 0,
        "end_age": 9,
        "duration_years": 9,
        "is_current": false
      },
      {
        "planet": "Saturn",
        "start_age": 9,
        "end_age": 23,
        "duration_years": 14,
        "is_current": false
      },
      {
        "planet": "Jupiter",
        "start_age": 23,
        "end_age": 35,
        "duration_years": 12,
        "is_current": false
      },
      {
        "planet": "Mars",
        "start_age": 27,
        "end_age": 34,
        "duration_years": 7,
        "is_current": true
      },
      {
        "planet": "Sun",
        "start_age": 34,
        "end_age": 44,
        "duration_years": 10,
        "is_current": false
      },
      {
        "planet": "Venus",
        "start_age": 44,
        "end_age": 52,
        "duration_years": 8,
        "is_current": false
      },
      {
        "planet": "Mercury",
        "start_age": 52,
        "end_age": 66,
        "duration_years": 14,
        "is_current": false
      }
    ],
    "natal_info": {
      "name": "Sample User",
      "datetime": "1992-03-20T10:15:00",
      "location": {
        "latitude": 37.5665,
        "longitude": 126.978,
        "timezone": "Asia/Seoul"
      }
    },
    "interpretation": {
      "description": "At age 28, you are in the Mars period (years 27-34).",
      "current_focus": "This is a time when Mars's significations are emphasized in your life.",
      "note": "The condition of natal Mars in your birth chart colors how this period unfolds.",
      "period_progress": "1 out of 7 years complete"
    }
  },
  "message": "Firdaria calculated successfully",
  "usage_info": {
    "feature": "firdaria",
    "user": "demo_user",
    "used": 9,
    "limit": 100,
    "remaining": 91
  }
}

응답 필드 설명

  • firdaria_info: Firdaria 계산 기본 정보
    • gender: 사용된 성별 (male/female)
    • current_age: 현재 나이
    • sequence_type: 사용된 순서 타입 (Male Diurnal / Female Nocturnal)
  • current_period: 현재 활성화된 행성 주기
    • ruling_planet: 현재 지배 행성
    • start_age / end_age: 주기 시작/종료 나이
    • years_into_period: 현재 주기 진행 연수
    • years_remaining: 주기 남은 연수
    • planet_themes: 해당 행성의 주요 테마
  • all_periods: 전체 Firdaria 주기 목록 (is_current 플래그 포함)
  • interpretation: 현재 주기에 대한 해석

에러 응답

나이 제한 초과 (400)

Firdaria 주기 범위 초과

응답 상태:400
{
  "success": false,
  "error": "Invalid request data: Age 80 is beyond the Firdaria cycle. Firdaria covers ages 0-74 years.",
  "error_code": 400,
  "details": null,
  "timestamp": "2025-10-30T17:30:00.123456"
}

잘못된 성별 값 (400)

성별 값 오류

응답 상태:400
{
  "success": false,
  "error": "Invalid value for 'body -> gender': Gender must be 'male', 'female', 'm', or 'f'",
  "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"
}

에러 코드 요약

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

사용 팁

  • 출생 차트와 연결: 현재 Firdaria 지배 행성이 출생 차트에서 어떤 상태에 있는지 확인하세요. 강한 행성의 주기는 더 긍정적으로 나타날 수 있습니다.
  • 트랜싯과 결합: 현재 Firdaria 행성에 대한 트랜싯을 특히 주의 깊게 관찰하세요. 그 행성이 "활성화"된 시기이므로 트랜싯의 영향이 더 두드러집니다.
  • Sub-Periods: 전통적으로 Firdaria는 더 세부적인 Sub-Periods로 나뉩니다. 현재 API는 Major Periods만 제공하지만, 추후 Sub-Periods도 추가될 예정입니다.
  • 주기 전환점: Firdaria 주기가 바뀌는 해(예: 18세, 32세 등)는 인생에서 중요한 전환점이 될 수 있습니다.
  • Profections와 비교: Annual Profections(매년 변경)와 달리 Firdaria는 장기 주기(7-14년)이므로, 두 기법을 함께 사용하면 단기/장기 타이밍을 모두 파악할 수 있습니다.

다음 단계

Annual Profections API

연간 하우스 프로펙션 계산

Natal Chart API

출생 차트 계산

Transits API

현재 행성 트랜싯

Progressions API

세컨더리 프로그레션 계산