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-сервер для ИИ-ассистентов

Те же расчёты доступны как MCP-сервер по адресу https://www.natalchart.ai/mcp для Claude, ChatGPT, Cursor и VS Code. Он принимает тот же ключ и расходует тот же суточный лимит, по одному запросу на каждый вызов инструмента. Настройка для каждого клиента описана на странице «MCP-сервер для ИИ-ассистентов».

Аутентификация

Передавайте ключ в заголовке 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 (supportive для тригона и секстиля, challenging для квадрата и оппозиции, intensifying для соединения) и 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 не включает её. Лимиты тоже раздельные: приложение считает ответы ИИ по неделям, этот API считает расчёты по суткам UTC, и ни один из лимитов не расходует другой.

Ошибки

У всех ошибок одна структура: { "error": { "code", "message", "details"?, "docs" } }.

Настройки расчёта

Эти настройки фиксированы и совпадают с настройками самого приложения: они подробно описаны на странице «Проверьте свою карту» и сверены с сервисом JPL Horizons от NASA в отчёте о точности. Файлы данных Swiss Ephemeris с включённым флагом скорости. Тропический зодиак, геоцентрические видимые положения. Дома по Плацидусу. Истинный лунный узел. Лилит как оскулирующий апогей Луны. Парс Фортуны по формуле ASC + Луна − Солнце, одинаково для дневных и ночных карт. Только пять мажорных аспектов: соединение 8°, секстиль 6°, квадрат 8°, тригон 8°, оппозиция 8°. Для каждого натального и транзитного аспекта указано, сходящийся он или расходящийся; это определяется по скоростям обоих тел с учётом ретроградного движения.

Конфиденциальность

Данные рождения относятся к персональным данным. API читает их, выполняет расчёт, отвечает и забывает их: тела запросов не сохраняются, и ничто из отправленного вами не используется ни для чего, кроме ответа. По каждому запросу мы храним эндпоинт, код статуса и время ответа. Подробнее в политике конфиденциальности.

Вопросы