Calculation transparency

Calculation Methodology and Known Limits

AstroAPI documents both the calculation it performs and the calculation it does not perform. Planet positions come from a bundled JPL DE421 ephemeris through Skyfield. House angles, lunar nodes, aspects, sidereal conversion, and timelines follow separate declared contracts with the boundaries below.

Read endpoint contracts Explore product uses

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 between −90 and 90; longitude must be finite and between −180 and 180.
  • Omitted timezone values default to UTC inside the shared engine, though individual public routes can impose stricter requirements.

Timezone is not inferred from coordinates. Supplying a local clock time with the wrong timezone changes the instant and can change every downstream result.

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 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, and krishnamurti; sidereal requests without an ayanamsa use Lahiri.

The three implementations retain defined J2000 base values and advance them with the IAU 2006/P03 general-precession polynomial. This coordinate conversion does not supply complete Vedic calendrical or interpretive logic. See Vedic-oriented building blocks for the exact scope.

House and angle calculations

AstroAPI computes sidereal time, right ascension of the meridian, Midheaven, and the eastern Ascendant using a fixed mean obliquity of 23.43704°. Sidereal output applies the selected ayanamsa to tropical Midheaven and Ascendant values.

Equal houses

The first cusp is the exact Ascendant; each next cusp advances 30 degrees.

Whole-sign houses

The first cusp is the start of the Ascendant's sign; each next cusp advances 30 degrees.

Placidus, Koch, Campanus, Regiomontanus, Porphyry, and other house systems are not currently implemented. The angle calculation is a documented fixed-obliquity approximation, not a Swiss Ephemeris house implementation. See the houses endpoint.

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.

The current response field labeled true is identical to the mean node. There is no nutation correction and no distinct true-node calculation, so this value must not be described as a precise true node.

Aspects, synastry, and transits

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.

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 endpoints do not produce compatibility scores, date-range event searches, applying/separating state, or exact ingress, egress, perfection, and station times.

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 crossing to a sub-second time window. Returned segments are contiguous and identify longitude at both ends plus retrograde residence.

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.

Validation and accuracy boundary

Regression tests cover selected golden positions, tropical/sidereal frame agreement, invalid zodiac handling, natal-to-transit output, gap-free timeline segments, retrograde crossings, Rahu/Ketu support, and request timeout behavior. Changes to ephemeris data, frames, formulas, rounding, or supported identifiers require focused comparisons and contract review.

Passing the current fixtures proves only those enumerated cases. It is not independent scientific validation of every date, body, timezone, coordinate, tradition, or third-party implementation. Differences are possible where methods and definitions differ.

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.