---
title: "Calculate natal geometry with optional graha drishti or partial Shadbala foundation"
method: POST
path: "/api/astro/natal-analysis"
tags: ["Calculations"]
---

# Calculate natal geometry with optional graha drishti or partial Shadbala foundation

`POST /api/astro/natal-analysis`

## Request

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

Uses selected Sun-through-Pluto apparent geocentric longitudes from the existing DE440 chart model. Returns every configured aspect within its inclusive orb, optional two-antipodal midpoint axes, and exact configuration matches for Grand Trine, T-square, Grand Cross, and Yod. An explicit additional_points list may also request Vertex/Antivertex, Equatorial Ascendant/Descendant, and the sect-reversed Lots of Fortune/Spirit; these are returned separately and are not silently added to aspects or patterns. Strict include_graha_drishti true additionally requires explicit zodiac sidereal and returns only seven classical-graha, whole-sign, full Parashari aspects under ruleset parashari_whole_sign_full_aspects_v1. Nodes, partial strengths, dignity, interpretation, prediction, and claims of universal Jyotish practice are excluded. Omission preserves the predecessor response byte-for-byte. At most ten geometric points, six additional points, eleven unique aspect definitions, 45 midpoint axes, and seven graha-drishti rows. One standard quota unit per admitted request; failed or timed-out admitted attempts are not refunded.
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
  - NatalAnalysisRequest: aspect_profile and aspects are mutually exclusive. Omit both to preserve the existing standard calculation. Graha drishti is separately opt-in and never changes the existing geometric aspects.
    - `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
    - `points` PlanetaryEventBody[]
    - `additional_points` AdditionalChartPoint[]
    - `aspect_profile` 'major' | 'standard' | 'extended': Neutral preset name. major uses five Ptolemaic aspects; standard preserves the existing six-aspect natal-analysis default; extended admits all eleven documented geometric aspects.
    - `aspects` NatalAnalysisAspectOption[]
      - `aspect` 'conjunction' | 'semisextile' | 'semisquare' | 'sextile' | 'quintile' | 'square' | 'trine' | 'sesquiquadrate' | 'biquintile' | 'quincunx' | 'opposition', required
      - `max_orb_degrees` number, required
    - `include_midpoints` boolean
    - `include_patterns` boolean
    - `include_graha_drishti` boolean: Opt in to the named Parashari whole-sign full-aspect ruleset. true requires an explicit sidereal zodiac.
    - `include_shadbala_foundation` boolean: Opt in to an explicitly partial BPHS chapter 27 strength foundation. It does not return a Shadbala total and true requires an explicit sidereal zodiac.
    - `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.
  - HistoricalNatalAnalysisRequest: 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
    - `points` string[]
    - `additional_points` string[]
    - `aspect_profile` 'major' | 'standard' | 'extended': Neutral preset name. major uses five Ptolemaic aspects; standard preserves the existing six-aspect natal-analysis default; extended admits all eleven documented geometric aspects.
    - `aspects` object[]
      - `aspect` 'conjunction' | 'semisextile' | 'semisquare' | 'sextile' | 'quintile' | 'square' | 'trine' | 'sesquiquadrate' | 'biquintile' | 'quincunx' | 'opposition', required
      - `max_orb_degrees` number, required
    - `include_midpoints` boolean
    - `include_patterns` boolean
    - `include_graha_drishti` boolean: Opt in to the named Parashari whole-sign full-aspect ruleset. true requires an explicit sidereal zodiac.
    - `include_shadbala_foundation` boolean: Opt in to an explicitly partial BPHS chapter 27 strength foundation. It does not return a Shadbala total and true requires an explicit sidereal zodiac.
    - `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.

## Response `200`

Bounded configurable geometric natal analysis.

- union
  - NatalAnalysisResponse
    - `status` 'current', required
    - `type` 'natal_analysis', required
    - `input` object, required
    - `points` object, required
    - `aspects` NatalAnalysisAspect[], required
      - `body_a` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
      - `body_b` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
      - `aspect` 'conjunction' | 'semisextile' | 'semisquare' | 'sextile' | 'quintile' | 'square' | 'trine' | 'sesquiquadrate' | 'biquintile' | 'quincunx' | 'opposition', required
      - `exact_angle_degrees` number, required
      - `separation_degrees` number, required
      - `orb_degrees` number, required
      - `max_orb_degrees` number, required
    - `midpoint_axes` NatalMidpointAxis[], required
      - `body_a` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
      - `body_b` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
      - `axis_longitudes_degrees` number[], required
      - `opposition_ambiguous` boolean, required
    - `patterns` NatalAspectPattern[], required
      - `type` 'grand_trine' | 't_square' | 'grand_cross' | 'yod', required
      - `bodies` PlanetaryEventBody[], required
      - `supporting_aspects` object[], required
    - `additional_points` AdditionalPointsResult
      - `points` AdditionalChartPointMap, required
        - `vertex` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
        - `antivertex` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
        - `equatorial_ascendant` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
        - `equatorial_descendant` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
        - `lot_of_fortune` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
        - `lot_of_spirit` AdditionalChartPointPosition
          - `label` 'Vertex' | 'Antivertex' | 'Equatorial Ascendant' | 'Equatorial Descendant' | 'Lot of Fortune' | 'Lot of Spirit', required
          - `category` 'angle' | 'lot', required
          - `longitude_degrees` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `degree_in_sign` number, required
      - `metadata` object, required
        - `model` 'cosmicephemeris-natal-points-v1', required
        - `status` 'current', required
        - `frame` 'apparent_ecliptic_of_date', 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
        - `chart_sect` 'day' | 'night', required
        - `sect_boundary` 'apparent_topocentric_sun_center_strictly_above_geometric_horizon', required
        - `vertex_definition` 'western_intersection_of_prime_vertical_and_ecliptic', required
        - `equatorial_ascendant_definition` 'ascendant_at_geographic_latitude_zero', required
        - `lot_formula` string, required
        - `interpretations` unknown, required
    - `graha_drishti` GrahaDrishtiResult
      - `ruleset` 'parashari_whole_sign_full_aspects_v1', required
      - `grahas` GrahaDrishtiRow[], required
        - `graha` 'sun' | 'moon' | 'mars' | 'mercury' | 'jupiter' | 'venus' | 'saturn', required
        - `sidereal_longitude_degrees` number, required
        - `source_sign_index` integer, required
        - `source_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `aspects` GrahaDrishtiAspect[], required
          - `relative_house` 3 | 4 | 5 | 7 | 8 | 9 | 10, required
          - `target_sign_index` integer, required
          - `target_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `aspected_grahas` GrahaDrishtiGraha[], required
      - `metadata` object, required
        - `aspect_model` 'whole_sign_full_aspects', required
        - `counting` 'inclusive_from_source_sign', required
        - `boundaries` 'half_open_lower_inclusive', required
        - `nodes` 'excluded_as_sources_and_targets', required
        - `partial_aspect_strengths` unknown, required
        - `interpretations` unknown, required
        - `frame` 'apparent_geocentric_sidereal_retained_nutation', required
        - `ayanamsa` string, nullable, required: 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.
        - `practitioner_review` 'not_completed', required
    - `shadbala_foundation` ShadbalaFoundationResult
      - `ruleset` 'parashara_bphs_chapter_27_strength_foundation_v1', required
      - `status` 'partial', required
      - `unit` 'virupa', required
      - `ascendant` object, required
        - `sidereal_longitude_degrees` number, required
        - `sign_index` integer, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
      - `planets` object, required
        - `sun` ShadbalaFoundationPlanet, required
          - `sidereal_longitude_degrees` number, required
          - `source_sign_index` integer, required
          - `source_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `whole_sign_house` integer, required
          - `navamsa_sign_index` integer, required
          - `navamsa_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `decan` integer, required
          - `sthana_bala_foundation` object, required
            - `uccha` number, required
            - `ojhayugma_rashi` 0 | 15, required
            - `ojhayugma_navamsa` 0 | 15, required
            - `kendradi` 15 | 30 | 60, required
            - `drekkana` 0 | 15, required
            - `subtotal` number, required
          - `naisargika_bala` number, required
          - `included_component_sum` number, required
        - `moon` ShadbalaFoundationPlanet, required
          - `sidereal_longitude_degrees` number, required
          - `source_sign_index` integer, required
          - `source_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `whole_sign_house` integer, required
          - `navamsa_sign_index` integer, required
          - `navamsa_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `decan` integer, required
          - `sthana_bala_foundation` object, required
            - `uccha` number, required
            - `ojhayugma_rashi` 0 | 15, required
            - `ojhayugma_navamsa` 0 | 15, required
            - `kendradi` 15 | 30 | 60, required
            - `drekkana` 0 | 15, required
            - `subtotal` number, required
          - `naisargika_bala` number, required
          - `included_component_sum` number, required
        - `mars` ShadbalaFoundationPlanet, required
          - `sidereal_longitude_degrees` number, required
          - `source_sign_index` integer, required
          - `source_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `whole_sign_house` integer, required
          - `navamsa_sign_index` integer, required
          - `navamsa_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `decan` integer, required
          - `sthana_bala_foundation` object, required
            - `uccha` number, required
            - `ojhayugma_rashi` 0 | 15, required
            - `ojhayugma_navamsa` 0 | 15, required
            - `kendradi` 15 | 30 | 60, required
            - `drekkana` 0 | 15, required
            - `subtotal` number, required
          - `naisargika_bala` number, required
          - `included_component_sum` number, required
        - `mercury` ShadbalaFoundationPlanet, required
          - `sidereal_longitude_degrees` number, required
          - `source_sign_index` integer, required
          - `source_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `whole_sign_house` integer, required
          - `navamsa_sign_index` integer, required
          - `navamsa_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `decan` integer, required
          - `sthana_bala_foundation` object, required
            - `uccha` number, required
            - `ojhayugma_rashi` 0 | 15, required
            - `ojhayugma_navamsa` 0 | 15, required
            - `kendradi` 15 | 30 | 60, required
            - `drekkana` 0 | 15, required
            - `subtotal` number, required
          - `naisargika_bala` number, required
          - `included_component_sum` number, required
        - `jupiter` ShadbalaFoundationPlanet, required
          - `sidereal_longitude_degrees` number, required
          - `source_sign_index` integer, required
          - `source_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `whole_sign_house` integer, required
          - `navamsa_sign_index` integer, required
          - `navamsa_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `decan` integer, required
          - `sthana_bala_foundation` object, required
            - `uccha` number, required
            - `ojhayugma_rashi` 0 | 15, required
            - `ojhayugma_navamsa` 0 | 15, required
            - `kendradi` 15 | 30 | 60, required
            - `drekkana` 0 | 15, required
            - `subtotal` number, required
          - `naisargika_bala` number, required
          - `included_component_sum` number, required
        - `venus` ShadbalaFoundationPlanet, required
          - `sidereal_longitude_degrees` number, required
          - `source_sign_index` integer, required
          - `source_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `whole_sign_house` integer, required
          - `navamsa_sign_index` integer, required
          - `navamsa_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `decan` integer, required
          - `sthana_bala_foundation` object, required
            - `uccha` number, required
            - `ojhayugma_rashi` 0 | 15, required
            - `ojhayugma_navamsa` 0 | 15, required
            - `kendradi` 15 | 30 | 60, required
            - `drekkana` 0 | 15, required
            - `subtotal` number, required
          - `naisargika_bala` number, required
          - `included_component_sum` number, required
        - `saturn` ShadbalaFoundationPlanet, required
          - `sidereal_longitude_degrees` number, required
          - `source_sign_index` integer, required
          - `source_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `whole_sign_house` integer, required
          - `navamsa_sign_index` integer, required
          - `navamsa_sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `decan` integer, required
          - `sthana_bala_foundation` object, required
            - `uccha` number, required
            - `ojhayugma_rashi` 0 | 15, required
            - `ojhayugma_navamsa` 0 | 15, required
            - `kendradi` 15 | 30 | 60, required
            - `drekkana` 0 | 15, required
            - `subtotal` number, required
          - `naisargika_bala` number, required
          - `included_component_sum` number, required
      - `metadata` object, required
        - `included_components` string[], required
        - `excluded_components` string[], required
        - `kendradi_house_model` 'whole_sign_from_sidereal_ascendant_sign', required
        - `boundaries` 'half_open_lower_inclusive', required
        - `nodes` 'excluded', required
        - `interpretations` unknown, required
        - `predictions` unknown, required
        - `practitioner_review` 'not_completed', required
        - `frame` 'apparent_geocentric_sidereal_retained_nutation', required
        - `ayanamsa` string, nullable, required: 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.
    - `metadata` object, required
  - HistoricalNatalAnalysisNatalAnalysisResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'natal-analysis', required
    - `input` HistoricalNatalAnalysisRequest, 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
      - `points` string[]
      - `additional_points` string[]
      - `aspect_profile` 'major' | 'standard' | 'extended': Neutral preset name. major uses five Ptolemaic aspects; standard preserves the existing six-aspect natal-analysis default; extended admits all eleven documented geometric aspects.
      - `aspects` object[]
        - `aspect` 'conjunction' | 'semisextile' | 'semisquare' | 'sextile' | 'quintile' | 'square' | 'trine' | 'sesquiquadrate' | 'biquintile' | 'quincunx' | 'opposition', required
        - `max_orb_degrees` number, required
      - `include_midpoints` boolean
      - `include_patterns` boolean
      - `include_graha_drishti` boolean: Opt in to the named Parashari whole-sign full-aspect ruleset. true requires an explicit sidereal zodiac.
      - `include_shadbala_foundation` boolean: Opt in to an explicitly partial BPHS chapter 27 strength foundation. It does not return a Shadbala total and true requires an explicit sidereal zodiac.
      - `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.
    - `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.
- `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.
- `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)