네이탈 차트 API

기본 URL: https://api.natalchart.ai. 모든 요청에는 API 키가 들어가고, 모든 응답은 JSON이며, 모든 황경은 도 단위로 소수점 넷째 자리까지 구한 다음 별자리로 환산합니다. 키는 무료입니다. NatalChart.AI 계정으로 로그인한 뒤 키를 만들면 됩니다.

빠른 시작

curl https://api.natalchart.ai/v1/chart/short \
  -H "Authorization: Bearer $NATALCHART_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"birth":{"date":"1991-09-06","time":"18:30","latitude":50.4501,"longitude":30.5234}}'

이 사이트 전체에서 쓰는 데모 출생 정보(1991-09-06, 18:30, 키이우)에 대한 응답입니다. 천체는 다섯 개만 보여 줍니다:

{
  "sun": {
    "sign": "Virgo",
    "degreeInSign": 13.55,
    "house": 7
  },
  "moon": {
    "sign": "Leo",
    "degreeInSign": 19.02,
    "house": 7
  },
  "ascendant": {
    "sign": "Aquarius",
    "degreeInSign": 14.9898
  },
  "signs": {
    "Sun": "Virgo",
    "Moon": "Leo",
    "Mercury": "Leo",
    "Venus": "Leo",
    "Mars": "Libra"
  },
  "retrograde": [
    "Venus",
    "Saturn",
    "Uranus",
    "Neptune",
    "TrueNode",
    "Lilith",
    "Juno"
  ]
}

AI 어시스턴트용 MCP 서버

같은 계산을 https://www.natalchart.ai/mcp의 MCP 서버로도 제공하며, Claude, ChatGPT, Cursor, VS Code에서 쓸 수 있습니다. 같은 키를 쓰고 같은 일일 한도에서 차감되며, 도구 호출 한 번에 요청 1회가 쓰입니다. 클라이언트별 설정 방법: AI 어시스턴트용 MCP 서버.

인증

키는 Authorization: Bearer nc_live_... 형식으로 보냅니다(X-API-Key 헤더도 쓸 수 있습니다). 전체 키는 만들 때 한 번만 표시되며, 저희는 키의 해시만 보관합니다. 계정 하나에 활성 키를 최대 5개까지 둘 수 있고, 어떤 키든 즉시 폐기할 수 있습니다. 키는 서버에 보관해야 합니다. 브라우저나 앱 코드에 넣어 배포한 키는 누구나 읽을 수 있습니다.

출생 정보

차트를 계산하는 엔드포인트는 객체 하나를 받습니다:

{
  "birth": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timezone": "Europe/Kyiv"
  }
}

엔드포인트

전체 차트

POST /v1/chart/full 엔드포인트는 계산 전체를 공개된 데모 파일과 같은 구조로 반환하므로, 코드를 쓰기 전에 고정된 차트와 응답을 대조해 볼 수 있습니다. 아래는 천체 두 개, 커스프 두 개, 오브가 가장 좁은 애스펙트 두 개로 줄인 예시입니다:

{
  "input": {
    "date": "1991-09-06",
    "time": "18:30",
    "latitude": 50.4501,
    "longitude": 30.5234,
    "timeKnown": true
  },
  "time": {
    "timezone": "Europe/Kyiv",
    "offsetHours": 3,
    "julianDayUT": 2448506.1458333335
  },
  "planets": [
    {
      "name": "Sun",
      "longitude": 163.5457,
      "sign": "Virgo",
      "degreeInSign": 13.55,
      "speed": 0.9704,
      "retrograde": false,
      "house": 7
    },
    {
      "name": "Moon",
      "longitude": 139.0225,
      "sign": "Leo",
      "degreeInSign": 19.02,
      "speed": 14.5955,
      "retrograde": false,
      "house": 7
    }
  ],
  "angles": {
    "ascendant": {
      "longitude": 314.9898,
      "sign": "Aquarius"
    },
    "midheaven": {
      "longitude": 249.8956,
      "sign": "Sagittarius"
    }
  },
  "houses": [
    {
      "number": 1,
      "cusp": 314.9898,
      "sign": "Aquarius"
    },
    {
      "number": 2,
      "cusp": 13.7492,
      "sign": "Aries"
    }
  ],
  "aspects": [
    {
      "planet1": "Pallas",
      "planet2": "Juno",
      "aspect": "Square",
      "angle": 89.79,
      "orb": 0.21,
      "phase": "separating"
    },
    {
      "planet1": "Pluto",
      "planet2": "TrueNode",
      "aspect": "Sextile",
      "angle": 59.57,
      "orb": 0.43,
      "phase": "separating"
    }
  ],
  "elements": {
    "Fire": 7,
    "Earth": 6,
    "Air": 4,
    "Water": 2
  },
  "qualities": {
    "Cardinal": 6,
    "Fixed": 11,
    "Mutable": 2
  }
}

세그먼트 엔드포인트(planets, angles, houses, aspects, elements, fixed-stars)는 각각 같은 객체의 한 부분만 반환하며, 그 부분만 필요한 호출에 씁니다.

일일 운세

POST /v1/horoscope/daily 엔드포인트는 일일 운세 중 계산으로 구하는 절반을 맡습니다. UTC 정오의 하늘, 달의 위상과 별자리, 앞으로 일주일의 하늘 이벤트를 반환하고, birth 필드를 보내면 그 차트에 대한 모든 트랜짓을 애스펙트, 오브, 접근 중인지 분리 중인지, 정확해지는 시각 또는 정확했던 시각, 트랜짓 천체가 놓인 네이탈 하우스와 함께 반환합니다. 트랜짓 오브는 달, 태양, 수성, 금성, 화성이 2°, 그보다 느린 천체가 3°입니다. 두 필드는 천문학이 아니라 고정된 규칙이며, 응답에도 그렇게 밝혀 둡니다. tone 필드(삼각과 육분은 supportive, 사각과 충은 challenging, 합은 intensifying)와, 행성의 속도와 오브의 좁기로 순위가 가장 높은 접촉 3개를 담은 focus 필드입니다. 작성된 글은 없으며, 그 부분은 직접 채울 몫입니다.

데모 차트의 2026-09-18 실제 응답입니다. 목록은 두 항목씩으로 줄였습니다:

{
  "date": "2026-09-18",
  "computedFor": "2026-09-18T12:00:00.000Z",
  "moon": {
    "phase": "First Quarter",
    "illumination": 46.5,
    "elongation": 86.04,
    "sign": "Sagittarius",
    "longitude": 261.6344,
    "degreeInSign": 21.63,
    "theme": "Decision + Action",
    "nextNewMoon": {
      "utc": "2026-10-10T15:50:05.436Z",
      "sign": "Libra",
      "degreeInSign": 17.36,
      "absoluteDegree": 197.36
    },
    "nextFullMoon": {
      "utc": "2026-09-26T16:49:02.781Z",
      "sign": "Aries",
      "degreeInSign": 3.62,
      "absoluteDegree": 3.62
    }
  },
  "positions": [
    {
      "name": "Sun",
      "longitude": 175.5994,
      "sign": "Virgo",
      "degreeInSign": 25.6,
      "speed": 0.9761,
      "retrograde": false
    },
    {
      "name": "Moon",
      "longitude": 261.6344,
      "sign": "Sagittarius",
      "degreeInSign": 21.63,
      "speed": 11.8869,
      "retrograde": false
    }
  ],
  "events": [
    {
      "kind": "ingress",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    },
    {
      "kind": "equinox",
      "at": "2026-09-23T00:05:13.524Z",
      "planet": "sun",
      "sign": "Libra",
      "degreeInSign": 0.01
    }
  ],
  "transits": [
    {
      "transit": "Vesta",
      "natal": "Mercury",
      "aspect": "Trine",
      "angle": 119.93,
      "orb": 0.07,
      "phase": "applying",
      "exactAt": "2026-09-18T21:43:39.997Z",
      "tone": "supportive",
      "transitHouse": 2,
      "houseTheme": "Money & Possessions"
    },
    {
      "transit": "Uranus",
      "natal": "Lilith",
      "aspect": "Trine",
      "angle": 119.86,
      "orb": 0.14,
      "phase": "separating",
      "exactAt": null,
      "tone": "supportive",
      "transitHouse": 3,
      "houseTheme": "Communication & Learning"
    }
  ],
  "focus": [
    {
      "transit": "Pluto",
      "natal": "Mars",
      "aspect": "Trine",
      "angle": 119.78,
      "orb": 0.22,
      "phase": "separating",
      "exactAt": "2026-09-03T17:58:04.996Z",
      "tone": "supportive",
      "transitHouse": 12,
      "houseTheme": "Spirituality & Subconscious"
    },
    {
      "transit": "Neptune",
      "natal": "Mars",
      "aspect": "Opposition",
      "angle": 179.74,
      "orb": 0.26,
      "phase": "separating",
      "exactAt": "2026-09-09T00:24:29.005Z",
      "tone": "challenging",
      "transitHouse": 1,
      "houseTheme": "Identity & Self"
    },
    {
      "transit": "Jupiter",
      "natal": "Moon",
      "aspect": "Conjunction",
      "angle": 1.77,
      "orb": 1.77,
      "phase": "applying",
      "exactAt": "2026-09-27T20:40:07.004Z",
      "tone": "intensifying",
      "transitHouse": 7,
      "houseTheme": "Partnerships & Marriage"
    }
  ]
}

API Pro 엔드포인트

엔드포인트 6개로, 모두 합치면 앱이 계산하는 모든 것이 됩니다. 아래의 각 예시는 데모 차트에 대한 실제 응답을 줄인 것이며, 요청에 있는 "..." 자리에는 위에 나온 출생 정보 객체가 들어갑니다.

기간별 트랜짓

POST /v1/transits 엔드포인트는 birth, from, to 필드(기간은 최대 92일)를 받아, 그 기간 안에서 네이탈 차트에 대한 트랜짓 애스펙트가 정확해지는 모든 시점을 날짜별로 반환하고, 모든 별자리 진입과 모든 정지도 반환합니다. 첫날에 작용 중인 접촉도 각각의 위상, 정확해지는 시각과 함께 반환합니다.

{
  "window": {
    "from": "2026-09-18",
    "to": "2026-10-18"
  },
  "events": [
    {
      "kind": "aspect",
      "date": "2026-09-19",
      "body": "Mercury",
      "target": "Neptune",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-22",
      "body": "Jupiter",
      "target": "Pluto",
      "aspect": "Square",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-23",
      "body": "Sun",
      "target": "Saturn",
      "aspect": "Trine",
      "exactness": 0,
      "significance": "low"
    },
    {
      "kind": "aspect",
      "date": "2026-09-26",
      "body": "Sun",
      "target": "Mars",
      "aspect": "Conjunction",
      "exactness": 0,
      "significance": "low"
    }
  ]
}

시나스트리

POST /v1/synastry 엔드포인트는 personA, personB 필드를 받아 오브를 포함한 차트 간 애스펙트, 각자의 행성이 상대의 어느 하우스에 들어가는지, 삶의 여섯 영역 각각의 점수를 반환합니다. 여기서 두 번째 사람의 정보도 가상으로 만든 것입니다(1989-03-14, 07:45, 뉴욕).

{
  "aspects": [
    {
      "personA": "Neptune",
      "personB": "Lilith",
      "aspect": "Trine",
      "angle": 120.08,
      "orb": 0.08
    },
    {
      "personA": "Saturn",
      "personB": "Jupiter",
      "aspect": "Trine",
      "angle": 119.66,
      "orb": 0.34
    },
    {
      "personA": "Mercury",
      "personB": "Moon",
      "aspect": "Sextile",
      "angle": 60.38,
      "orb": 0.38
    }
  ],
  "sphereScores": {
    "identity": 89,
    "love": 81,
    "body": 86,
    "money": 76,
    "home": 83,
    "mind": 66
  }
}

솔라 리턴

POST /v1/solar-return 엔드포인트는 birth, year 필드와 선택 항목인 location 필드를 받아, 태양이 네이탈 황경으로 돌아오는 정확한 시각과 그 시각으로 계산한 전체 차트를 반환합니다. 출생 시간이 필요합니다. 출생 시간이 없으면 네이탈 태양의 위치가 0.5도만큼 불확실해지고, 이 때문에 리턴 시각이 약 12시간 달라집니다.

{
  "year": 2027,
  "exactMomentUtc": "2027-09-06T08:29:55Z",
  "location": {
    "latitude": 50.4501,
    "longitude": 30.5234
  },
  "chart": "the full chart of that moment, in the shape of /v1/chart/full"
}

활동하기 좋은 날

POST /v1/timing 엔드포인트는 birth 필드, activity 필드(general, business, romance, health, creative, travel, home, clarity 중 하나), from, to 필드(기간은 최대 62일), 그리고 하루가 시작되는 기준을 정하는 선택 항목인 timezone 필드를 받습니다. 하루하루의 점수는 트랜짓의 정확한 기하 배치를 바탕으로 0에서 100까지 매기고, 그 활동에 중요한 행성에 가중치를 두며, 가장 좋은 5일이 먼저 나옵니다. 하늘을 설명할 뿐, 어떤 날을 약속하지는 않습니다.

{
  "activity": "business",
  "best": [
    {
      "date": "2026-10-12",
      "score": 69.5,
      "rating": "good",
      "moonPhase": "New Moon",
      "moonSign": "Scorpio",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Moon (0.2°)",
        "Transit Mercury Sextile Sun (0.3°)",
        "Transit Mercury Sextile Neptune (0.2°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.8°)"
      ]
    },
    {
      "date": "2026-10-14",
      "score": 63.5,
      "rating": "good",
      "moonPhase": "Waxing Crescent",
      "moonSign": "Sagittarius",
      "voidOfCourse": false,
      "favorableAspects": [
        "Transit Sun Sextile Venus (1.1°)",
        "Transit Moon Sextile Saturn (0.7°)",
        "Transit Jupiter Conjunction Venus (0.1°)"
      ],
      "challengingAspects": [
        "Transit Saturn Square Uranus (0.7°)",
        "Transit Saturn Square Uranus (0.6°)"
      ]
    }
  ]
}

차트를 기준으로 본 한 장소

POST /v1/locations/score 엔드포인트는 birth 필드와 좌표를 담은 location 필드를 받습니다. 차트를 그 장소 기준으로 다시 계산하며, 응답에는 리로케이션 차트의 앵글, 앵글에 놓인 행성과 오브, 삶의 영역마다 0에서 10까지의 점수(5가 중립), 그리고 차트가 그 장소에 얼마나 강하게 반응하는지가 담깁니다. 주요 행성이 앵글에서 2° 이내에 있으면 강함, 4° 이내면 보통, 그 밖에는 약함입니다.

{
  "relocated": {
    "ascendant": {
      "longitude": 277.7847,
      "sign": "Capricorn"
    },
    "midheaven": {
      "longitude": 210.708,
      "sign": "Scorpio"
    }
  },
  "angularPlanets": [
    {
      "planet": "Uranus",
      "angle": "ASC",
      "orb": 2.12,
      "weight": "major",
      "strength": "strong"
    },
    {
      "planet": "Neptune",
      "angle": "ASC",
      "orb": 6.31,
      "weight": "major",
      "strength": "weak"
    }
  ],
  "spheres": {
    "identity": {
      "score10": 1,
      "verdict": "challenging"
    },
    "love": {
      "score10": 6.1,
      "verdict": "slightly supportive"
    },
    "body": {
      "score10": 3.2,
      "verdict": "challenging"
    },
    "money": {
      "score10": 2.2,
      "verdict": "challenging"
    },
    "home": {
      "score10": 1.7,
      "verdict": "challenging"
    },
    "mind": {
      "score10": 4.9,
      "verdict": "neutral"
    }
  },
  "overall10": 2.2,
  "strength": "moderate"
}

차트에 가장 좋은 도시

POST /v1/locations/rank 엔드포인트는 birth 필드, 선택 항목인 focus 필드(identity, love, body, money, home, mind 중 원하는 것), 선택 항목인 region 필드, 3에서 12까지의 limit 필드를 받아 주요 도시 61곳의 목록에 순위를 매깁니다. 지구상의 모든 도시를 비교하는 것은 아니며, 다른 장소는 위의 엔드포인트로 점수를 매길 수 있습니다.

{
  "comparedCities": 61,
  "top": [
    {
      "city": "New York",
      "country": "United States",
      "overall10": 7.4,
      "focus10": 8.3,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.6°",
        "Moon MC 2.3°"
      ]
    },
    {
      "city": "Tbilisi",
      "country": "Georgia",
      "overall10": 7.4,
      "focus10": 8.2,
      "strength": "moderate",
      "contacts": [
        "Sun DSC 3.3°"
      ]
    },
    {
      "city": "Montreal",
      "country": "Canada",
      "overall10": 7.4,
      "focus10": 8.1,
      "strength": "strong",
      "contacts": [
        "Venus MC 0.1°",
        "Moon MC 2.8°",
        "Mercury MC 3.8°"
      ]
    }
  ]
}

한도와 요금

요청은 계정 단위로, 계정의 모든 키를 합산해 세며, 한도는 UTC 기준 00:00에 다시 채워집니다. 모든 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset 헤더가 붙습니다. 유효하지 않아 거부된 요청은 세지 않고, 저희 쪽에서 실패한 계산은 한도에 되돌려 드리며, GET /v1/usage 요청은 언제나 무료입니다. API Pro는 앱 요금제와 별개인 구독입니다. API Pro에는 앱의 Premium이 포함되지 않고, 앱의 Premium에도 API Pro가 포함되지 않습니다. 두 한도도 서로 별개입니다. 앱은 AI 답변을 주 단위로 세고, 이 API는 계산을 UTC 기준 하루 단위로 세며, 어느 쪽도 다른 쪽의 한도를 쓰지 않습니다.

오류

모든 오류는 같은 형태입니다: { "error": { "code", "message", "details"?, "docs" } }.

계산 설정

설정은 고정되어 있으며 앱 자체의 설정과 같습니다. 내 차트 검증하기 페이지에 모두 설명되어 있고, 정확도 보고서에서 NASA의 JPL Horizons와 대조해 확인합니다. Swiss Ephemeris 데이터 파일 사용, 속도 플래그 켬. 트로피컬 조디악, 지구 중심, 겉보기 위치. 플라시더스 하우스. 진교점. 릴리스는 달의 접촉 원지점. 행운의 점은 낮 차트와 밤 차트 모두 ASC + 달 − 태양. 주요 애스펙트 5가지만 사용: 합 8°, 육분 6°, 사각 8°, 삼각 8°, 충 8°. 모든 네이탈 애스펙트와 트랜짓 애스펙트에는 접근 중인지 분리 중인지가 표시되며, 역행을 포함한 두 천체의 속도로 판단합니다.

개인정보 보호

출생 정보는 개인정보입니다. API는 출생 정보를 읽고, 계산하고, 응답한 뒤 잊습니다. 요청 본문은 저장하지 않으며, 보낸 정보는 응답 외의 어떤 용도로도 쓰지 않습니다. 요청마다 보관하는 것은 엔드포인트, 상태 코드, 지연 시간입니다. 자세한 내용은 개인정보 처리방침에서 볼 수 있습니다.

자주 묻는 질문