Назад к документации

Натальная карта (западная)

Натальная карта (западная)

POST/api/v1/natal/calculate

Создайте профессиональную западную натальную карту с поддержкой нескольких систем домов, точные скорости планет, обнаружение станций, дополнительные тела (астероиды и узлы) и явная поддержка рождения без времени через time_known.

Полный URL

https://api.freeastroapi.com/api/v1/natal/calculate
Safe retries with Idempotency-Key

Authenticated, billable astrology POST requests accept the optional header Idempotency-Key: <client-generated unique operation key>. Reuse the same key only when retrying the exact same method, path, query string, and JSON body after a timeout or network failure.

A completed replay returns the first response with Idempotency-Replayed: true, does not rerun the calculation, and does not consume extra quota. Keys are retained for about 24 hours.

Reusing a key with a changed request returns 409 idempotency_key_reused. A duplicate while the first request is still running returns 409 request_in_progress with Retry-After.

Параметры тела запроса

ParameterTypeReqDescription
namestringНетИмя субъекта (для отображения)
yearintegerДаГод рождения (например, 1990)
monthintegerДаМесяц рождения (1-12)
dayintegerДаДень рождения (1-31)
time_knownbooleanНетПо умолчанию: true. Установите значение false, если время рождения неизвестно. В этом режиме дома и углы опускаются, расположение домов планет не возвращается, а метаданные достоверности понижаются.
hourintegerНетЧас рождения (0-23, 24-часовой формат). Требуется, когда time_known=true. Структурно игнорируется, если time_known=false.
minuteintegerНетМинута рождения (0-59). Требуется, когда time_known=true. Структурно игнорируется, если time_known=false.
citystringДаНазвание города (используется для поиска координат через /geo/search)
latfloatНетШирота (от -90 до 90). Необязательно: автоматически определяется из города, если не указано иное.
lngfloatНетДолгота (от -180 до 180). Необязательно: автоматически определяется из города, если не указано иное.
tz_strstringНетСтрока часового пояса (например, 'Europe/Paris' или 'AUTO'). По умолчанию: AUTO
house_systemstringНетplacidus (по умолчанию), whole_sign, equal, koch, regiomontanus, porphyry, campanus
zodiac_typestringНетtropical (по умолчанию) или sidereal. Sidereal использует указанную ayanamsa.
fixed_starsarray[str]НетПредпочтительный селектор с фиксированной звездой. Принимает идентификаторы пакетов, такие как royal_4 и behenian_20, точные названия звезд, такие как Spica, или all для полного набора по умолчанию. Пример: ["royal_4", "Спика"]. .

Пример кода

curl -X POST "https://api.freeastroapi.com/api/v1/natal/calculate" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "name": "John Doe",
    "year": 1990,
    "month": 5,
    "day": 15,
    "time_known": true,
    "hour": 14,
    "minute": 30,
    "city": "New York",
    "lat": 40.7128,
    "lng": -74.006,
    "tz_str": "AUTO",
    "response_format": "full",
    "house_system": "placidus",
    "zodiac_type": "tropical",
    "include_speed": true,
    "include_dignity": true,
    "include_minor_aspects": true,
    "include_stelliums": true,
    "fixed_stars": ["royal_4", "Spica"],
    "include_features": ["chiron", "lilith", "true_node"],
    "interpretation": {
        "enable": true,
        "style": "improved"
    },
    "orb_settings": {
        "Conjunction": 8.0,
        "Opposition": 8.0,
        "Trine": 8.0,
        "Square": 8.0,
        "Sextile": 6.0
    }
}'

Производительность и оптимизация v2.2

Compression

Мы поддерживаем Бротли (бр) сжатие для максимальной скорости. Убедитесь, что ваш клиент отправляет Accept-Кодировка: br, gzip.

Caching

Натальные карты неизменны. Ответы включают Cache-Control: общедоступный, максимальный возраст = 31536000, неизменяемый. Вы можете безопасно кэшировать результаты на неопределенный срок, чтобы минимизировать вызовы API.

Данные ответа

{
  "subject": {
    "name": "John Doe",
    "city": "New York",
    "...": "...",
    "settings": {
      "house_system": "placidus",
      "julian_day": 2448032.27083,
      "delta_t_days": -0.0000339,
      "delta_t_seconds": -2.93,
      "zodiac_type": "Tropical",
      "time_known": true
    }
  },

  "planets": [
    {
      "id": "sun",
      "name": "Sun",
      "sign": "Tau",
      "pos": 24.72,
      "abs_pos": 54.72,
      "house": 9,
      "retrograde": false,
      "speed": 0.96,
      "is_stationary": false
    },
    {
      "id": "moon",
      "name": "Moon",
      "sign": "Aqu",
      "pos": 14.23,
      "abs_pos": 314.23,
      "house": 5,
      "retrograde": false,
      "speed": 12.45,
      "is_stationary": false
    },
    {
      "id": "chiron",
      "name": "Chiron",
      "sign": "Can",
      "pos": 12.34,
      "abs_pos": 102.34,
      "house": 11,
      "retrograde": false,
      "speed": 0.05,
      "is_stationary": false
    }
    // Note: ASC is in "angles" object, not in "planets" array
  ],

  "houses": [
    { "house": 1, "name": "1", "sign": "Can", "sign_id": "cancer", "pos": 8.92, "abs_pos": 98.92 },
    { "house": 2, "name": "2", "sign": "Leo", "sign_id": "leo", "pos": 26.17, "abs_pos": 116.17 },
    // ... houses 3-11
    { "house": 12, "name": "12", "sign": "Gem", "sign_id": "gemini", "pos": 9.45, "abs_pos": 69.45 }
  ],

  "angles": {
    "asc": 98.92268897761204,   // Ascendant: absolute longitude (0-360°)
    "mc": 339.333397447316,    // Midheaven (MC)
    "ic": 159.333397447316,    // Imum Coeli (IC) - opposite MC
    "dc": 278.92268897761204,  // Descendant - opposite ASC
    "vertex": 235.34043201194  // Vertex point
  },

  "angles_details": {
    "asc": { "sign": "Can", "sign_id": "cancer", "pos": 8.92268897761204, "abs_pos": 98.92268897761204, "house": 1 },
    "mc": { "sign": "Pis", "sign_id": "pisces", "pos": 9.333397447316, "abs_pos": 339.333397447316, "house": 10 },
    "ic": { "sign": "Vir", "sign_id": "virgo", "pos": 9.333397447316, "abs_pos": 159.333397447316, "house": 4 },
    "dc": { "sign": "Cap", "sign_id": "capricorn", "pos": 8.92268897761204, "abs_pos": 278.92268897761204, "house": 7 },
    "vertex": { "sign": "Sco", "sign_id": "scorpio", "pos": 25.34043201194, "abs_pos": 235.34043201194, "house": 5 }
  },

  "aspects": [
    {
      "p1": "Sun",
      "p2": "Moon",
      "type": "Square",
      "orb": 5.51,
      "deg": 90.0,
      "is_major": true
    }
  ],

  "stelliums": {
    "threshold": 3,
    "signs": [
      { "sign_id": "taurus", "count": 3, "bodies": ["mercury", "sun", "venus"] }
    ],
    "houses": [],
    "total": 1
  },

  "fixed_stars": {
    "Regulus": {
      "id": "fixed_star_regulus",
      "name": "Regulus",
      "sign": "Leo",
      "sign_id": "leo",
      "pos": 29.7,
      "abs_pos": 149.7,
      "house": 2
    }
  },

  "confidence": {
    "houses": "high",
    "angles": "high",
    "overall": "high"
  },

  "interpretation": {
    "metadata": {
      "key_count": 57,
      "found_count": 57,
      "missing_keys": []
    },
    "sections": {
      "core_self": [
        {
          "id": "b86f87d3-2ea7-4dba-b1be-a667f4435584",
          "key": "planet.sun.sign.taurus",
          "category": "planet_sign",
          "title": "Sun in Taurus",
          "body": "Sun in Taurus emphasizes steadiness, material awareness, and a measured approach to life...",
          "tone": "improved",
          "tags": ["sun", "taurus"],
          "created_at": "2026-02-04T09:10:16.104443+00:00",
          "updated_at": "2026-02-04T09:10:16.104443+00:00"
        }
      ],
      "mind": [
        {
          "id": "fdea3513-56db-4349-b55e-87cb382ab520",
          "key": "planet.mercury.sign.taurus",
          "category": "planet_sign",
          "title": "Mercury in Taurus",
          "body": "Mercury in Taurus shapes a steady, deliberate mind...",
          "tone": "improved",
          "tags": ["mercury", "taurus"],
          "created_at": "2026-02-04T09:11:25.614751+00:00",
          "updated_at": "2026-02-04T09:11:25.614751+00:00"
        }
      ],
      "love_relating": [],
      "work_path": [],
      "social_collective": [],
      "karmic_healing": [
        {
          "id": "9ae37083-cadc-4a57-b3ac-7ec99645f0eb",
          "key": "planet.chiron.sign.cancer",
          "category": "planet_sign",
          "title": "Chiron in Cancer",
          "body": "Chiron in Cancer highlights a longstanding sensitivity around belonging...",
          "tone": "improved",
          "tags": ["chiron", "cancer"],
          "created_at": "2026-02-04T09:26:12.302848+00:00",
          "updated_at": "2026-02-04T09:26:12.302848+00:00"
        }
      ],
      "aspects": [
        {
          "p1": "moon",
          "p2": "sun",
          "type": "trine",
          "key": "aspect.moon.trine.sun",
          "title": "Sun Trine Moon",
          "content": "Sun trine Moon reflects an easy flow between instinct and intention..."
        }
      ]
    }
  }
} 

Пример ответа без точного времени

{
  "subject": {
    "name": "Jane Doe",
    "settings": {
      "house_system": "placidus",
      "zodiac_type": "Tropical",
      "time_known": false
    }
  },
  "planets": [
    {
      "id": "sun",
      "name": "Sun",
      "sign": "Sco",
      "sign_id": "scorpio",
      "pos": 10.84,
      "abs_pos": 220.84,
      "retrograde": false
    },
    {
      "id": "north_node",
      "name": "North Node",
      "sign": "Sag",
      "sign_id": "sagittarius",
      "pos": 2.18,
      "abs_pos": 242.18,
      "retrograde": true,
      "variant": "true"
    },
    {
      "id": "chiron",
      "name": "Chiron",
      "sign": "Leo",
      "sign_id": "leo",
      "pos": 14.02,
      "abs_pos": 134.02,
      "retrograde": false
    }
  ],
  "aspects": [
    {
      "p1": "moon",
      "p2": "sun",
      "type": "trine",
      "orb": 1.42,
      "deg": 120,
      "is_major": true
    }
  ],
  "confidence": {
    "houses": "unavailable",
    "angles": "unavailable",
    "overall": "medium"
  }
}

FAQ

Предоставляет ли эта эндпоинт визуальную диаграмму как SVG или PNG?

Нет. Эндпоинт Natal возвращает только расчетные данные карты; он не генерирует визуальные изображения карты в SVG или PNG. Используйте Эндпоинт западного графика SVG when you need a visual chart.

Ваш API возвращает параллели?

Да. Эндпоинт Натала может возвращать параллели склонения и контрпараллели, если вы согласитесь с"include_declination_aspects": true. По умолчанию они не возвращаются.

{
  "include_declination_aspects": true,
  "declination_orb": 1.0
}

Результаты возвращаются под declination_aspects и резюмировано вdeclination_aspects_summary. Регулярные аспекты долготы остаются подaspects.

Связанные эндпоинты