Calculation Methodology and Known Limits

Methodology at a glance

Ephemeris

Bundled JPL DE421

Default frame

Tropical, apparent geocentric longitude

Accepted dates

1900-01-01 through 2050-12-31

A request reaches the public API gateway, which authenticates the API key and applies plan, quota, concurrency, timeout, and usage controls. An internal calculation service normalizes time and location inputs, evaluates the requested calculation, and returns JSON. The ephemeris is packaged with the service; it is not downloaded during a calculation.

Dates, local time, and location

• A public chart date must fall within 1900-01-01 through 2050-12-31, inclusive.
• Use an IANA timezone such as America/New_York when the submitted time is local civil time.
• The timezone database resolves the local input and converts the instant to UTC before ephemeris evaluation.
• Latitude must be finite and strictly between −90 and 90; longitude must be finite and between −180 and 180. Exact geographic poles have no defined rising Ascendant and are rejected.
• Dates use YYYY-MM-DD; times use HH:MM or HH:MM:SS. Nonexistent or ambiguous local times at clock changes are rejected. For a repeated hour, submit the known UTC date/time with timezone: "UTC".
• Omitted timezone values default to UTC inside the shared engine, though individual public routes can impose stricter requirements.

Planet positions and motion

The chart engine observes from Earth and extracts apparent geocentric ecliptic longitude for the Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, and Pluto. Jupiter through Pluto use the barycenter keys available in DE421.

Each body includes longitude rounded to four decimals, its sign and degree within that sign, and an apparent one-day signed longitude difference. A negative difference sets the returned retrograde flag. This is not a refined station time or a high-precision velocity.

The API does not currently return topocentric planet or point positions, right ascension, declination, altitude, azimuth, distance, or observer-specific parallax corrections.

Tropical and sidereal longitude

Tropical is the default zodiac. Sidereal is an explicit opt-in that subtracts a date-aware ayanamsa from tropical longitude and normalizes the result to 0–360 degrees. Supported identifiers are lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian, true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, and galactic_alignment_mardyks; sidereal requests without an ayanamsa use Lahiri.

The mean implementations use defined J2000 anchors and the IAU 2006/P03 general-precession polynomial; true-star and Galactic Center modes use their documented apparent-place anchors. This coordinate conversion does not supply complete Vedic calendrical or interpretive logic. See Vedic-oriented building blocks for the exact scope.

Cosmic Ephemeris subtracts the selected date-aware ayanamsa from apparent tropical longitude, retaining nutation. This is a declared frame convention, not exact interchangeability with another astrology engine. In 930 comparisons across 1900–2050 and all three modes, sidereal planetary longitude differed from Swiss Ephemeris/Moshier by at most 19 arcseconds. Near a sign, nakshatra, or pada boundary, small frame differences can change the label or crossing time.

House and angle calculations

Cosmic Ephemeris computes apparent sidereal time, right ascension of the meridian, Midheaven, and the eastern Ascendant using date-dependent true obliquity from Skyfield's coordinate frames. Sidereal output applies the selected ayanamsa to tropical Midheaven and Ascendant values.

Placidus is an opt-in beta semiarc calculation; it rejects its undefined polar domain without substituting another system. Porphyry is an opt-in beta on the Houses and natal-SVG endpoints: each ecliptic quadrant between the four chart angles is divided into thirds. Meridian, Campanus, Regiomontanus, Alcabitius, Koch, Morinus, Topocentric, Sripati, Vehlow, Horizon/Azimuth, Krusinski-Pisa-Goelzer, Sunshine, Sunshine alternative, Savard-A, Pullen SD, Pullen SR, Carter Poli-Equatorial, APC, Equal MC, and Natural are also opt-in calculation-only betas on those two endpoints; Gauquelin is an additional Houses-only beta because its map contains 36 sectors rather than twelve cusps; each rejects unsupported geometry without fallback. Topocentric here means Polich/Page house cusps only; planet positions remain geocentric. Sripati uses the forward midpoints of Porphyry sectors and keeps physical angles separate. Vehlow uses equal 30-degree houses with the physical Ascendant centered in house 1 and keeps MC separate. Horizon/Azimuth projects twelve equal local-horizon sectors through vertical circles to the ecliptic; cusp 1 is not the physical Ascendant and cusp 10 is MC. Krusinski-Pisa-Goelzer projects equal Ascendant-zenith great-circle divisions through celestial meridian circles; cusps 1 and 10 are the physical angles. Sunshine uses the Treindl construction from trisected solar diurnal and nocturnal semi-arcs; cusps 1 and 10 are the physical angles. Sunshine alternative independently uses Makransky prime-vertical geometry for the same trisected solar house points. Savard-A projects one-third and two-thirds geographic-latitude circles through the prime vertical; cusps 1 and 10 are the physical angles and opposite cusps are antipodal. Pullen SD redistributes each ecliptic quadrant's deviation from 90 degrees with quarter/half/quarter weighting; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Pullen SR proportions complementary quadrant house widths as rx, x, rx and r³x, r⁴x, r³x; cusp 10 is the physical Midheaven and cusp 1 uses the orientation-adjusted Ascendant. Carter divides right ascension into twelve equal arcs from the orientation-adjusted Ascendant and projects them to the ecliptic; cusp 10 is generally not the physical Midheaven. APC divides the Ascendant parallel into six sectors below and six above the horizon; cusps 1 and 10 are the orientation-adjusted angles and intermediate opposite cusps are not generally antipodal. Equal MC fixes the physical Midheaven at cusp 10 and places twelve equal 30-degree ecliptic houses; cusp 1 is generally not the physical Ascendant. Natural places house 1 at Aries and every cusp on a selected-zodiac sign boundary, independently of physical angles. Gauquelin divides diurnal and nocturnal semiarcs into 36 clockwise sectors, anchored at Ascendant sector 1 and Midheaven sector 10, and is not rendered by Natal SVG. For Equal and Whole Sign, eastern-horizon selection also applies at polar latitudes; exact geographic poles and coincident horizon/ecliptic geometry are rejected rather than assigned an arbitrary Ascendant. These are original Cosmic Ephemeris implementations, not Swiss Ephemeris runtime integration. See the houses endpoint.

Additional natal points

Natal analysis and natal SVG accept an explicit opt-in selection of Vertex, Antivertex, Equatorial Ascendant/Descendant, and the Lots of Fortune/Spirit. Vertex is the western prime-vertical/ecliptic intersection. The Equatorial Ascendant is the latitude-zero Ascendant; the API avoids the ambiguous “East Point” name.

Fortune and Spirit use unrounded apparent Sun/Moon longitudes and documented day/night reversal. Day means the apparent topocentric Sun center is strictly above the geometric horizon. The points remain separate from planets and are not automatically included in aspects or interpretations. Omission preserves the existing calculation and SVG shape.

Lunar nodes

The engine uses a Meeus-style mean ascending-node polynomial. The south node is the mean north node plus 180 degrees. Tropical or sidereal conversion follows the selected chart frame.

Separate osculating-node beta

The lunar-nodes endpoint calculates a distinct geometric DE421 osculating node from the same-instant Moon–Earth position and inertial velocity. Its true pair uses true ecliptic/equinox-of-date axes; its mean pair retains the mean-node polynomial and mean date axes. Each model identifies its frame before optional sidereal subtraction. The true model retains nutation under the existing date-aware ayanamsa convention; it applies no light time, aberration or observer-location correction. Coordinates are not accepted.

The separate beta does not change chart nodes or timeline Rahu/Ketu. Four decimal degrees are an output resolution, not an accuracy guarantee. Instantaneous osculating geometry is not a universal true-node definition or an eclipse prediction.

Bounded solar and lunar returns

The return beta finds the next Sun or Moon crossing of its unrounded natal longitude in the selected zodiac. Apparent geocentric longitudes use each ephemeris date's frame and, for sidereal, its date-aware date-aware ayanamsa. A fixed one-millisecond exclusion after the supplied search instant treats an already-reached return as the current cycle.

Fixed 370-day Sun and 32-day Moon windows in uniform TT must fit inside the supported UTC range. Two-day Sun or six-hour Moon samples bracket the first forward crossing; bisection requires a bracket at most 0.001 seconds wide and residual at most 1e-7 degrees, with at most 48 refinement iterations. These numerical limits do not establish equivalent physical event accuracy. The physical chart uses the solved instant directly, selected return coordinates and Equal or Whole Sign houses. Its existing mean-node fields remain unchanged. Preserve leap-second-aware UTC output as a string.

Solar-arc directions and deeper Vimshottari periods

Solar arcs use the unrounded apparent tropical Sun's direct movement under the existing TT day-for-year mapping. That one arc rotates natal planets and angles; sidereal output retains the natal-date ayanamsa. Directed Equal/Whole Sign houses are synthetic, not a geographically solved event chart.

Deeper Vimshottari subdivides each antardasha into nine Pratyantardashas and, at depth four, each of those into nine Sookshma periods. The fixed 729/6,561 leaves use exact integer-microsecond durations and half-open intervals. The 365.25-day year, birth balance, default two-level output and depth-three response are unchanged. Arithmetic checks do not establish acceptance across every Jyotish convention or predictive validity.

Davison, divisional charts, Moon calendars and planetary events

Davison calculates the physical sky at the uniform-TT mean of two birth instants and an arithmetic midpoint of their canonical coordinates. It does not average planet longitudes like a symbolic composite. This uncorrected beta does not implement corrected-MC or spherical variants; preserve leap-second-aware UTC strings.

D1/D2/D3/D4/D5/D6/D7/D8/D9/D10/D11/D12/D16/D20/D24/D27/D30/D40/D45/D60/D81/D108/D144/D150 classify unrounded sidereal longitudes using named divisional mappings and half-open boundaries. The same results feed North/South Indian SVGs. D30 uses documented unequal Parashari segments, D60 uses the source-sign-plus-part convention, and D150 exposes only its eight named bounded mappings. Existing mappings and defaults remain unchanged; unlisted vargas, alternative conventions, and practitioner acceptance are not implied.

Moon phases use DE421 apparent geocentric geometry. Instant sectors describe the longitude cycle, while illuminated fraction is a separate geometric result. The bounded calendar solves four primary longitude-phase events; numerical convergence is not physical timing accuracy. Opt-in iCalendar serializes those events without recalculation. Its assembly timestamp may differ between calls, and empty calendars return a null export. This is not eclipse or crescent-visibility prediction.

Planetary events use DE421 apparent geocentric ecliptic-of-date longitude to search at most 31 UTC days. Selected-zodiac sign boundaries, physical tropical-longitude stations and exact major-aspect crossings are refined from fixed six-hour samples. One-second output and a 0.05-second root bracket describe numerical resolution, not equivalent physical accuracy. No orb windows, tangencies, houses, eclipses or interpretations are supplied.

House ingresses calculate Equal or Whole Sign cusps once from a known reference birth, then search selected DE421 transit longitudes for direct and retrograde crossings of those fixed boundaries. This is not a moving-mundane-house search. Placidus and Porphyry remain excluded pending specialist acceptance.

Eclipse geometry searches at most 366 UTC days. Solar classification uses bundled DE421 Sun–Moon shadow-axis and cone geometry at its modeled global maximum; lunar classification uses Skyfield's Danjon shadow geometry. Optional observer coordinates add only a no-refraction snapshot at global maximum; this is not a local-maximum, contact-time or geographic-path service. The separate electional search applies documented AND-only filters at fixed one-hour samples over at most seven days; returned candidate windows summarize sampled bins and do not prove continuous satisfaction between samples.

Aspect windows reuse the exact crossing search and bracket the surrounding orb entry and exit with fixed three-hour stepping. Only contiguous intervals containing an exact hit are returned; tangential orb-only contacts are excluded. Boundaries outside the request are clipped and explicitly null. Optional RFC 5545 text is returned in JSON and does not write to external calendars.

Aspects, synastry, and transits

Legacy within-chart aspects evaluate each planet pair once using fixed maximum orbs. The supported aspects are conjunction, opposition, trine, square, sextile, semisextile, semisquare, quintile, sesquiquadrate, and biquintile. Output reports the matched aspect, its exact angle, the measured separation, and the resulting orb.

The bounded natal-analysis and natal-SVG beta routes also accept neutral major, standard, and extended profiles or a mutually exclusive custom table of unique aspect names and 0.1°–10.0° orbs. Each selected definition is tested independently, so broad custom orbs can report multiple selected aspects for one pair. Omission preserves the earlier route behavior. These controls do not alter legacy charts, synastry, transits, events, reports, or interpretations.

Synastry calculates two complete charts and then applies the shared cross-chart aspect helper. Transits calculate a natal chart and a chart for one requested transit instant, then compare every transit body with every natal body. These two endpoints do not produce compatibility scores, date-range event searches, applying/separating state, or exact ingress, egress, perfection, and station times. Use the separate planetary-events beta for its bounded exact-event inventory.

Review the aspect, synastry, and transit response contracts before building parsers.

Nakshatra and pada timelines

The timeline endpoint is always sidereal and divides the zodiac into 27 named nakshatras and four padas each. A fixed one-hour coarse sample brackets boundaries; bisection refines each detected crossing to a sub-second time window. Returned segments are contiguous and identify longitude at both ends. The retrograde flag reports net motion across a residence, not a guarantee of uniform motion if a station falls inside it.

Timeline intervals must be positive, no longer than 180 days, and within the public date range. Rahu maps to the mean north node and Ketu to the opposite south node. The endpoint supplies geometry, not dashas, yogas, Panchanga, or predictions. See the timeline contract.

Sub-second refinement describes numerical resolution within the chosen model, not absolute astronomical accuracy. An outward crossing and return entirely between hourly samples can be missed near a station. This endpoint is not a certified exhaustive station/event finder.

Validation and accuracy boundary

A September 14, 2026 comparison covered all ten planets at 31 epochs from 1900 through 2050 against an independent Swiss Ephemeris/Moshier calculation. All 310 tropical longitude comparisons were within 1.4 arcseconds. A separate 2,325-case location/time grid placed tropical Ascendant differences below 9 arcseconds and Midheaven differences below 2.2 arcseconds. These are measured sample results, not universal error bounds.

Acceptance checks also exercise every public calculation endpoint, all eleven supported ayanamsas, timezone equivalence and clock-change rejection, both house systems, all nine timeline bodies, retrograde windows, and plan/quota enforcement. Reference values are regression fixtures; Swiss Ephemeris is not a production dependency.

Calculation data and persistence

The internal Python calculation engine has no database credentials and writes no database records. The gateway records usage metadata. The current calculation schema does not intentionally persist birth inputs, chart payloads, or timeline segments as customer records. Operational services and logs can process related request metadata, so consult the current privacy notice before deciding what data your application sends.