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"
  ]
}

MCP-сервер для AI-асистентів

Ті самі обчислення доступні як MCP-сервер за адресою https://www.natalchart.ai/mcp для Claude, ChatGPT, Cursor і VS Code. Він приймає той самий ключ і витрачає той самий добовий ліміт: один запит на кожен виклик інструмента. Налаштування для кожного клієнта: MCP-сервер для AI-асистентів.

Автентифікація

Надсилайте ключ як Authorization: Bearer nc_live_... (заголовок X-API-Key теж підходить). Повний ключ показується один раз, коли ви його створюєте; ми зберігаємо лише його хеш. В акаунті може бути до п'яти активних ключів, і будь-який із них можна миттєво відкликати. Зберігайте ключі на сервері: ключ, вбудований у код для браузера чи застосунку, може прочитати будь-хто.

Дані народження

Ендпоінти, які обчислюють карту, приймають один об'єкт:

{
  "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 (тригон і секстиль сприятливі, квадрат і опозиція напружені, з'єднання посилює) і 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

Шість ендпоінтів, які разом охоплюють усе, що обчислює застосунок. Кожен приклад нижче це справжня відповідь для демонстраційної карти в скороченому вигляді; "..." у запиті позначає об'єкт із даними народження, наведений вище.

Транзити за період

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 та повертає точний момент, коли Сонце знову доходить до своєї натальної довготи, разом із повною картою, побудованою на цей момент. Потрібен час народження: без нього положення натального Сонця невизначене в межах пів градуса, а це зсуває момент соляра приблизно на дванадцять годин.

{
  "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 за точною геометрією транзитів, зважену за планетами, важливими для цієї справи, і п'ять найкращих днів ідуть першими. Ендпоінт описує небо і не обіцяє, яким буде день.

{
  "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 і limit від 3 до 12 та ранжує великі міста з каталогу, де їх 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°"
      ]
    }
  ]
}

Ліміти й тарифи

Запити рахуються на рівні акаунта, сумарно за всіма його ключами, а ліміт поновлюється о 00:00 UTC. Кожна відповідь містить X-RateLimit-Limit, X-RateLimit-Remaining і X-RateLimit-Reset. Запит, відхилений як некоректний, не зараховується, обчислення, яке не вдалося з нашого боку, повертається в ліміт, а GET /v1/usage завжди безкоштовний. API Pro це окрема підписка, не пов'язана з планами застосунку: вона не включає Premium у застосунку, а Premium у застосунку не включає її. Ліміти теж окремі: застосунок рахує відповіді AI за тижнями, цей API рахує обчислення за добами UTC, і жоден не витрачає ліміт іншого.

Помилки

Усі помилки мають однакову структуру: { "error": { "code", "message", "details"?, "docs" } }.

Налаштування обчислень

Ці налаштування фіксовані й збігаються з налаштуваннями самого застосунку; їх повністю описано на сторінці Перевірте свою карту і звірено з JPL Horizons від NASA у звіті про точність. Файли даних Swiss Ephemeris з увімкненим прапорцем швидкості. Тропічний зодіак, геоцентричні видимі положення. Доми за Плацидусом. Істинний місячний вузол. Ліліт як оскулюючий апогей Місяця. Колесо Фортуни як ASC + Місяць − Сонце, однаково для денних і нічних карт. Лише п'ять мажорних аспектів: з'єднання 8°, секстиль 6°, квадрат 8°, тригон 8°, опозиція 8°. Для кожного натального й транзитного аспекту вказано, сходиться він чи розходиться; це визначається за швидкостями обох тіл, з урахуванням ретроградності.

Конфіденційність

Дані народження є персональними даними. API читає їх, обчислює, відповідає й забуває: жодне тіло запиту не зберігається, і ніщо з надісланого вами не використовується ні для чого, крім відповіді. Для кожного запиту ми зберігаємо ендпоінт, код статусу й час відповіді. Дивіться політику конфіденційності.

Запитання