---
title: "Calculate a full birth chart"
method: POST
path: "/api/astro/birth-chart"
tags: ["Calculations"]
---

# Calculate a full birth chart

`POST /api/astro/birth-chart`

## Request

- Base URL: `https://api.cosmicephemeris.com`
- URL: `https://api.cosmicephemeris.com/api/astro/birth-chart`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Current unversioned gateway response.

Each admitted request reserves one monthly usage unit before route validation or engine work; failed or timed-out admitted attempts are not refunded. Do not automatically retry.

## Request body

- union
  - ModernBirthChartRequest: Only supported ayanamsa names are valid when zodiac is sidereal; tropical retains its legacy ignore behavior.
    - `date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
    - `time` string, required: HH:MM or HH:MM:SS; no offset in this field. Use timezone to select the civil-time zone.
    - `timezone` string, nullable: IANA timezone name (for example America/New_York). Omission, null, or empty string means UTC for a birth input. Nonexistent or ambiguous local clock-change times return 400; provide the known UTC date/time with timezone UTC instead.
    - `lat` union, required: WGS84 decimal latitude. JSON numbers are recommended; numeric strings are accepted by the current engine, then checked for finiteness/range. Exact poles and undefined Ascendant geometry return 400; supported successful latitude is strictly between -90 and 90. Boolean/null/object/array coordinates are invalid.
      - number
      - string
    - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
      - number
      - string
    - `zodiac` string, nullable: tropical or sidereal; server trims whitespace and ignores case. Omitted/null selects tropical.
    - `ayanamsa` string, nullable: Sidereal supports lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian, true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, galactic_alignment_mardyks, with case/whitespace normalization; other names return 400 in sidereal mode. Omitted/null selects lahiri. Tropical mode ignores a nonempty string and outputs null. This schema describes that compatibility behavior rather than claiming every string is a supported sidereal model.
  - HistoricalBirthChartRequest: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
    - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
      - `year` integer, required
      - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
      - `month` integer, required
      - `day` integer, required
      - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
    - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
    - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
    - `lat` union, required: WGS84 decimal latitude. JSON numbers are recommended; numeric strings are accepted by the current engine, then checked for finiteness/range. Exact poles and undefined Ascendant geometry return 400; supported successful latitude is strictly between -90 and 90. Boolean/null/object/array coordinates are invalid.
      - number
      - string
    - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
      - number
      - string
    - `zodiac` string, nullable: tropical or sidereal; server trims whitespace and ignores case. Omitted/null selects tropical.
    - `ayanamsa` string, nullable: Sidereal supports lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian, true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, galactic_alignment_mardyks, with case/whitespace normalization; other names return 400 in sidereal mode. Omitted/null selects lahiri. Tropical mode ignores a nonempty string and outputs null. This schema describes that compatibility behavior rather than claiming every string is a supported sidereal model.
    - `house_system` 'equal' | 'whole_sign' | 'placidus' | 'porphyry' | 'meridian' | 'campanus' | 'regiomontanus' | 'alcabitius' | 'koch' | 'morinus' | 'topocentric' | 'sripati' | 'vehlow' | 'horizon' | 'krusinski' | 'sunshine' | 'sunshine_alt' | 'savard' | 'pullen_sd' | 'pullen_sr' | 'carter' | 'apc' | 'equal_mc' | 'natural' | 'gauquelin'

## Response `200`

Successful calculation. Field nesting is specific to this route.

- BirthChartResponse
  - `type` 'birth-chart', required
  - `input` BirthChartEcho, required: Original input values with omitted/null timezone replaced by UTC. Omitted zodiac/ayanamsa remain absent; use chart fields for normalized results. Numeric coordinate strings remain strings here.
    - `date` union, required
      - string, date: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
      - HistoricalDate: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
        - `year` integer, required
        - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
        - `month` integer, required
        - `day` integer, required
        - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
    - `time` string, required: HH:MM or HH:MM:SS; no offset in this field. Use timezone to select the civil-time zone.
    - `timezone` string, nullable, required: IANA timezone name (for example America/New_York). Omission, null, or empty string means UTC for a birth input. Nonexistent or ambiguous local clock-change times return 400; provide the known UTC date/time with timezone UTC instead.
    - `lat` union, required: WGS84 decimal latitude. JSON numbers are recommended; numeric strings are accepted by the current engine, then checked for finiteness/range. Exact poles and undefined Ascendant geometry return 400; supported successful latitude is strictly between -90 and 90. Boolean/null/object/array coordinates are invalid.
      - number
      - string
    - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
      - number
      - string
    - `zodiac` string, nullable: tropical or sidereal; server trims whitespace and ignores case. Omitted/null selects tropical.
    - `ayanamsa` string, nullable: Sidereal supports lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian, true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, galactic_alignment_mardyks, with case/whitespace normalization; other names return 400 in sidereal mode. Omitted/null selects lahiri. Tropical mode ignores a nonempty string and outputs null. This schema describes that compatibility behavior rather than claiming every string is a supported sidereal model.
  - `chart` Chart, required: A full calculation chart, not a rendered wheel or interpretation. Sidereal longitudes subtract the selected documented date-aware ayanamsa from apparent tropical longitudes; this is not a promise of identity with every ephemeris convention.
    - `status` 'ok', required
    - `zodiac` 'tropical' | 'sidereal', required
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', required
    - `planets` Planets, required
      - `Sun` PlanetPosition, required: Apparent geocentric JPL DE440 ecliptic position. sidereal_lon is present in sidereal mode; nakshatra is present only on the sidereal Moon.
        - `lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
        - `speed_deg_per_day` number, required: Signed tropical longitude difference over the preceding one TT day, rounded to four decimals; not an instantaneous derivative.
        - `retrograde` boolean, required
        - `tropical_lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sidereal_lon` number: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `nakshatra` Nakshatra
          - `index` integer, required
          - `name` string, required
          - `ruler` string, required
          - `pada` integer, required
          - `deg_into_nakshatra` number, required
      - `Moon` PlanetPosition, required: Apparent geocentric JPL DE440 ecliptic position. sidereal_lon is present in sidereal mode; nakshatra is present only on the sidereal Moon.
        - `lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
        - `speed_deg_per_day` number, required: Signed tropical longitude difference over the preceding one TT day, rounded to four decimals; not an instantaneous derivative.
        - `retrograde` boolean, required
        - `tropical_lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sidereal_lon` number: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `nakshatra` Nakshatra
          - `index` integer, required
          - `name` string, required
          - `ruler` string, required
          - `pada` integer, required
          - `deg_into_nakshatra` number, required
      - `Mercury` PlanetPosition, required: Apparent geocentric JPL DE440 ecliptic position. sidereal_lon is present in sidereal mode; nakshatra is present only on the sidereal Moon.
        - `lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
        - `speed_deg_per_day` number, required: Signed tropical longitude difference over the preceding one TT day, rounded to four decimals; not an instantaneous derivative.
        - `retrograde` boolean, required
        - `tropical_lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sidereal_lon` number: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `nakshatra` Nakshatra
          - `index` integer, required
          - `name` string, required
          - `ruler` string, required
          - `pada` integer, required
          - `deg_into_nakshatra` number, required
      - `Venus` PlanetPosition, required: Apparent geocentric JPL DE440 ecliptic position. sidereal_lon is present in sidereal mode; nakshatra is present only on the sidereal Moon.
        - `lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
        - `speed_deg_per_day` number, required: Signed tropical longitude difference over the preceding one TT day, rounded to four decimals; not an instantaneous derivative.
        - `retrograde` boolean, required
        - `tropical_lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sidereal_lon` number: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `nakshatra` Nakshatra
          - `index` integer, required
          - `name` string, required
          - `ruler` string, required
          - `pada` integer, required
          - `deg_into_nakshatra` number, required
      - `Mars` PlanetPosition, required: Apparent geocentric JPL DE440 ecliptic position. sidereal_lon is present in sidereal mode; nakshatra is present only on the sidereal Moon.
        - `lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
        - `speed_deg_per_day` number, required: Signed tropical longitude difference over the preceding one TT day, rounded to four decimals; not an instantaneous derivative.
        - `retrograde` boolean, required
        - `tropical_lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sidereal_lon` number: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `nakshatra` Nakshatra
          - `index` integer, required
          - `name` string, required
          - `ruler` string, required
          - `pada` integer, required
          - `deg_into_nakshatra` number, required
      - `Jupiter` PlanetPosition, required: Apparent geocentric JPL DE440 ecliptic position. sidereal_lon is present in sidereal mode; nakshatra is present only on the sidereal Moon.
        - `lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
        - `speed_deg_per_day` number, required: Signed tropical longitude difference over the preceding one TT day, rounded to four decimals; not an instantaneous derivative.
        - `retrograde` boolean, required
        - `tropical_lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sidereal_lon` number: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `nakshatra` Nakshatra
          - `index` integer, required
          - `name` string, required
          - `ruler` string, required
          - `pada` integer, required
          - `deg_into_nakshatra` number, required
      - `Saturn` PlanetPosition, required: Apparent geocentric JPL DE440 ecliptic position. sidereal_lon is present in sidereal mode; nakshatra is present only on the sidereal Moon.
        - `lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
        - `speed_deg_per_day` number, required: Signed tropical longitude difference over the preceding one TT day, rounded to four decimals; not an instantaneous derivative.
        - `retrograde` boolean, required
        - `tropical_lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sidereal_lon` number: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `nakshatra` Nakshatra
          - `index` integer, required
          - `name` string, required
          - `ruler` string, required
          - `pada` integer, required
          - `deg_into_nakshatra` number, required
      - `Uranus` PlanetPosition, required: Apparent geocentric JPL DE440 ecliptic position. sidereal_lon is present in sidereal mode; nakshatra is present only on the sidereal Moon.
        - `lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
        - `speed_deg_per_day` number, required: Signed tropical longitude difference over the preceding one TT day, rounded to four decimals; not an instantaneous derivative.
        - `retrograde` boolean, required
        - `tropical_lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sidereal_lon` number: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `nakshatra` Nakshatra
          - `index` integer, required
          - `name` string, required
          - `ruler` string, required
          - `pada` integer, required
          - `deg_into_nakshatra` number, required
      - `Neptune` PlanetPosition, required: Apparent geocentric JPL DE440 ecliptic position. sidereal_lon is present in sidereal mode; nakshatra is present only on the sidereal Moon.
        - `lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
        - `speed_deg_per_day` number, required: Signed tropical longitude difference over the preceding one TT day, rounded to four decimals; not an instantaneous derivative.
        - `retrograde` boolean, required
        - `tropical_lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sidereal_lon` number: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `nakshatra` Nakshatra
          - `index` integer, required
          - `name` string, required
          - `ruler` string, required
          - `pada` integer, required
          - `deg_into_nakshatra` number, required
      - `Pluto` PlanetPosition, required: Apparent geocentric JPL DE440 ecliptic position. sidereal_lon is present in sidereal mode; nakshatra is present only on the sidereal Moon.
        - `lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
        - `speed_deg_per_day` number, required: Signed tropical longitude difference over the preceding one TT day, rounded to four decimals; not an instantaneous derivative.
        - `retrograde` boolean, required
        - `tropical_lon` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sidereal_lon` number: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `nakshatra` Nakshatra
          - `index` integer, required
          - `name` string, required
          - `ruler` string, required
          - `pada` integer, required
          - `deg_into_nakshatra` number, required
    - `houses` Houses, required: Legacy full-chart houses contain Equal and Whole Sign, sharing the eastern-horizon Ascendant and meridian MC. These chart routes do not opt into Placidus. The separate /houses selected-system response is described by SelectedHouses.
      - `ascendant` number, required
      - `mc` number, required
      - `systems` HouseSystems, required
        - `equal` HouseSystem
          - `name` 'Equal' | 'Whole sign', required
          - `houses` Cusps, required
            - `1` number, required
            - `2` number, required
            - `3` number, required
            - `4` number, required
            - `5` number, required
            - `6` number, required
            - `7` number, required
            - `8` number, required
            - `9` number, required
            - `10` number, required
            - `11` number, required
            - `12` number, required
        - `whole_sign` HouseSystem
          - `name` 'Equal' | 'Whole sign', required
          - `houses` Cusps, required
            - `1` number, required
            - `2` number, required
            - `3` number, required
            - `4` number, required
            - `5` number, required
            - `6` number, required
            - `7` number, required
            - `8` number, required
            - `9` number, required
            - `10` number, required
            - `11` number, required
            - `12` number, required
      - `metadata` object, required
        - `zodiac` 'tropical' | 'sidereal', required
        - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', required
    - `aspects` NatalAspect[], required
      - `p1` 'Sun' | 'Moon' | 'Mercury' | 'Venus' | 'Mars' | 'Jupiter' | 'Saturn' | 'Uranus' | 'Neptune' | 'Pluto', required
      - `p2` 'Sun' | 'Moon' | 'Mercury' | 'Venus' | 'Mars' | 'Jupiter' | 'Saturn' | 'Uranus' | 'Neptune' | 'Pluto', required
      - `type` 'conjunction' | 'opposition' | 'trine' | 'square' | 'sextile' | 'semisextile' | 'semisquare' | 'quintile' | 'sesquiquadrate' | 'biquintile', required
      - `exact_angle` 0 | 180 | 120 | 90 | 60 | 30 | 45 | 72 | 135 | 144, required
      - `distance` number, required
      - `orb` number, required
    - `nodes` Nodes, required
      - `mean` NodePosition, required
        - `longitude` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
      - `true` NodePosition, required
        - `longitude` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
      - `south` NodePosition, required
        - `longitude` number, required: Ecliptic longitude in degrees, displayed to four decimals. Rounding of a value just below 360 can produce 360.0; do not recompute sign/pada from rounded display values.
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required: Displayed to four decimals; rounding near the next sign can produce 30.0.
      - `note` string, required
    - `metadata` object, required
      - `note` string, required

## Other responses

- `400`: Invalid request, malformed JSON, out-of-range date/location, unknown model, invalid timezone or ambiguous/nonexistent clock-change time. Invalid attempts reaching quota reservation consume one unit.
- `401`: Missing, invalid, revoked API key or unavailable activated key owner. Dashboard cookies do not authenticate calculation routes.
- `403`: Origin not allowed by production CORS policy. Server-to-server requests can omit Origin.
- `404`: Wrong/case-variant/noncanonical or trailing-slash route; public paths have no version prefix.
- `413`: Request exceeds the body limit; gateway JSON is capped at 128 KiB. Edge failures may be HTML.
- `429`: Monthly quota exhausted, per-user two-request concurrency reached, or nginx rate/connection admission refused. Retry-After: 2 is sent for application per-user concurrency only, not a promise that monthly quota resets in two seconds.
- `500`: Bounded gateway/database/internal failure. An admitted attempt can still consume quota.
- `502`: Engine unavailable, unsuccessful internal server response or invalid upstream JSON. No engine internals are exposed.
- `503`: Four-request global calculation pool full (Retry-After: 2), maintenance or upstream service unavailable.
- `504`: Application engine timeout: 15 seconds normally; planetary events, house ingresses, aspect windows, event calendar, eclipse geometry, electional search, and event-rule search use 30 seconds; Nakshatra Timeline plus the explicitly enumerated readiness, robustness, location, uncertainty, and electional-audit family use 60 seconds. Timer includes response-body parsing; an admitted timeout consumes quota.

---

[API](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api.md) · [All operations](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/revisions/f041e924cea3?raw)