---
title: "Find the next solar or lunar return and its chart"
method: POST
path: "/api/astro/returns"
tags: ["Calculations"]
---

# Find the next solar or lunar return and its chart

`POST /api/astro/returns`

## Request

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

Current first solar or lunar longitude return beyond after +1 millisecond, subject to the documented numerical equality allowance, followed by a physical chart at that root. after may precede birth. Both civil dates 1800–2200; birth UTC and the complete fixed search window (Sun 370 TT days, Moon 32 TT days) must stay in UTC 1800–2200; no window clipping. Tropical/Equal defaults. Sidereal uses each ephemeris date's mean P03 ayanamsa with nutation retained. Return location defaults to birth coordinates and changes houses, not the return instant. No Placidus, arbitrary bodies/targets/search tolerances, cycles or predictions. All admitted attempts use one standard quota unit, including free plans. No practitioner sign-off is claimed.

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.
Historical mode uses an explicit BCE/CE date object and UT1 conventions. Its response is the versioned historical envelope, not the modern UTC envelope. Read result for calculation fields and metadata for limits and uncertainty.

## Request body

- union
  - ReturnsRequest: Supported first solar or lunar longitude return beyond after +1 millisecond, subject to the documented numerical equality allowance, followed by a physical chart at that root. after may precede birth. Both civil dates 1800–2200; birth UTC and the complete fixed search window (Sun 370 TT days, Moon 32 TT days) must stay in UTC 1800–2200; no window clipping. Tropical/Equal defaults. Sidereal uses each ephemeris date's mean P03 ayanamsa with nutation retained. Return location defaults to birth coordinates and changes houses, not the return instant. No Placidus, arbitrary bodies/targets/search tolerances, cycles or predictions.
    - `birth` CalculationBirthInput, required: Strict nested birth input; no unknown properties, nulls, booleans or numeric strings. Known civil time required; semantic date/DST/undefined-angle validation occurs on the server.
      - `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: Valid IANA zone; UTC when omitted. Ambiguous and nonexistent civil times are rejected.
      - `lat` number, required
      - `lon` number, required
    - `body` 'sun' | 'moon', required
    - `after` CivilTimeInput, required
      - `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
    - `zodiac` 'tropical' | 'sidereal'
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
    - `house_system` 'equal' | 'whole_sign'
    - `location` ReturnLocation
      - `lat` number, required
      - `lon` number, required
  - HistoricalReturnsRequest: 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.
    - `birth` HistoricalBirthInput, required
      - `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` number, required
      - `lon` number, required
    - `body` 'sun' | 'moon', required
    - `after` HistoricalDateTime, required: Shared historical input contract; parsing alone does not enable a calculation route. Derived calculation records can include fractional seconds and are not this input type.
      - `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.
    - `zodiac` 'tropical' | 'sidereal'
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
    - `house_system` 'equal' | 'whole_sign'
    - `location` ReturnLocation
      - `lat` number, required
      - `lon` number, required

## Response `200`

Successful calculation. Field nesting is specific to this route.

- union
  - ReturnsResponse
    - `type` 'returns', required
    - `status` 'current', required
    - `method` 'next_longitude_return', required
    - `body` 'sun' | 'moon', 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
    - `input` object, required
      - `birth` CalculationMomentResult, required
        - `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, required: Valid IANA zone; UTC when omitted. Ambiguous and nonexistent civil times are rejected.
        - `lat` number, required
        - `lon` number, required
      - `body` 'sun' | 'moon', required
      - `after` NormalizedCivilTime, required
        - `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, 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
      - `house_system` 'equal' | 'whole_sign', required
      - `location` ReturnLocation, required
        - `lat` number, required
        - `lon` number, required
    - `birth_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
    - `after_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
    - `return_utc` string, required: Root or bracket UTC instant with six fractional digits; actual leap second60 is preserved. JavaScript Date/Python datetime cannot directly parse second60. Numerical subsecond tolerance is not physical event-time accuracy. The single TT JD is a display/reference field; the chart is calculated using the two-part root Time object.
    - `natal_longitude_deg` number, required
    - `return_longitude_deg` number, required
    - `chart` ReturnChart, required: Existing chart serialization evaluated at the exact root Time object and requested location. Exactly one selected Equal/Whole Sign house system. Legacy chart mean-node aliases and rounding conventions remain unchanged; use lunar-nodes separately for a distinct osculating node model.
      - `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` object, required: Physical return-location houses; exactly one selected Equal/Whole Sign system.
        - `ascendant` number, required
        - `mc` number, required
        - `systems` object, required
          - `equal` HouseSystem
            - `name` 'Equal' | 'Whole sign', required
            - `houses` Cusps, required
              - …
          - `whole_sign` HouseSystem
            - `name` 'Equal' | 'Whole sign', required
            - `houses` Cusps, 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
    - `search` ReturnSearch, required
      - `time_scale` 'TT', required
      - `max_days` 370 | 32, required
      - `sample_step_days` 2 | 0.25, required
      - `samples` 186 | 129, required
      - `iterations` integer, required
      - `max_iterations` 48, required
      - `start_exclusion_seconds` 0.001, required
      - `root_tt_jd` number, required
      - `residual_deg` number, required
      - `angular_tolerance_deg` 1e-7, required
      - `time_tolerance_seconds` 0.001, required
      - `bracket` object, required
        - `start_utc` string, required: Root or bracket UTC instant with six fractional digits; actual leap second60 is preserved. JavaScript Date/Python datetime cannot directly parse second60. Numerical subsecond tolerance is not physical event-time accuracy. The single TT JD is a display/reference field; the chart is calculated using the two-part root Time object.
        - `end_utc` string, required: Root or bracket UTC instant with six fractional digits; actual leap second60 is preserved. JavaScript Date/Python datetime cannot directly parse second60. Numerical subsecond tolerance is not physical event-time accuracy. The single TT JD is a display/reference field; the chart is calculated using the two-part root Time object.
        - `width_seconds` number, required
    - `metadata` ReturnsMetadata, required
      - `ephemeris` 'JPL-DE440', required
      - `timescale_data` 'bundled-skyfield', required
      - `source_frame` 'apparent-geocentric-ecliptic-of-each-ephemeris-date', required
      - `target_policy` 'unrounded-natal-longitude-in-selected-zodiac', required
      - `sidereal_policy` 'per-ephemeris-date-mean-P03-ayanamsa-with-nutation-retained' | 'not-applicable', required
      - `search_policy` 'first-forward-crossing-after-one-millisecond-start-exclusion', required
      - `window_policy` 'full-fixed-TT-window-required-without-clipping', required
      - `location_policy` 'explicit-return-location' | 'birth-location', required
      - `chart_time_policy` 'root-Time-object-without-civil-roundtrip', required
      - `chart_precision` 'existing-chart-serialization', required
      - `utc_output` 'leap-second-aware-ISO-8601', required
      - `root_tt_jd_policy` 'display-only-single-float-not-used-for-chart', required
      - `root_precision` 'numerical-tolerance-not-physical-event-accuracy', required
      - `house_system` 'equal' | 'whole_sign', required
      - `nodes` 'existing-mean-node-contract', required
      - `aspects` 'existing-natal-longitude-orbs', required
      - `interpretations` false, required
      - `practitioner_review` 'not-completed', required
  - HistoricalReturnsResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'returns', required
    - `input` HistoricalReturnsRequest, required: 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.
      - `birth` HistoricalBirthInput, required
        - `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` number, required
        - `lon` number, required
      - `body` 'sun' | 'moon', required
      - `after` HistoricalDateTime, required: Shared historical input contract; parsing alone does not enable a calculation route. Derived calculation records can include fractional seconds and are not this input type.
        - `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.
      - `zodiac` 'tropical' | 'sidereal'
      - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
      - `house_system` 'equal' | 'whole_sign'
      - `location` ReturnLocation
        - `lat` number, required
        - `lon` number, required
    - `result` object, required: Complete historical calculation adapter result. Times are explicit UT1 date records, never UTC strings; derived times may include fractional seconds and years outside the input range.
    - `metadata` object, required
      - `time_standard` 'UT1', required
      - `historical_accuracy_certified` unknown, required
      - `warnings` 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)