Compute the zodiac position of a single body or point at a single moment.

Returns the geocentric ecliptic longitude, sign and degree within sign, daily motion, and retrograde state. Use for "where is X" questions rather than a full chart. Bodies: Sun through Pluto, plus NorthNode, SouthNode (mean lunar nodes), Lilith (mean lunar apogee / Black Moon Lilith), and Chiron (n-body from public JPL initial conditions).

Examples:

• "Where is Mars right now?" -> { body: "Mars" } (datetime defaults to now)

• "Was Mercury retrograde on 2026-01-01?" -> inspect retrograde in the result

• "Moon sign at 14:30 in Riga on 3 May 1985" -> { body: "Moon", datetime: "1985-05-03T14:30", timezone: "Europe/Riga" }

Compute a complete natal (birth) chart: the ten classical bodies plus lunar nodes, Lilith, and Chiron, house cusps, Ascendant and Midheaven, the Part of Fortune, and all aspects.

Accepts local birth time directly when given the IANA timezone — no manual UTC conversion needed. Supports tropical (Western) and sidereal (Vedic/Lahiri, Fagan-Bradley) zodiacs.

Examples:

• "Chart for 15 March 1990, 3:45pm in Riga" -> { datetime: "1990-03-15T15:45", timezone: "Europe/Riga", latitude: 56.95, longitude: 24.11 }

• Vedic chart: add { zodiac: "sidereal-lahiri" }

Returns: positions (13 points), houses (12 cusps + angles), the Part of Fortune (classical day/night formula, with the dayChart flag showing which applied), aspects, and the ayanamsa applied (0 for tropical).

Compute the aspects from a transiting sky to a natal chart — how the planets at one moment relate to the planets at a birth moment.

Examples:

• "What's transiting my chart today, born 1990-03-15 15:45 Riga time?" -> { natal_datetime: "1990-03-15T15:45", natal_timezone: "Europe/Riga" } (transit_datetime defaults to now)

For the exact date a specific transit perfects, use find_aspect_times instead.

Compute a secondary-progressed chart: the natal chart advanced one ephemeris day per year of life (the standard "day-for-a-year" method). Shows how the chart has symbolically evolved by a given date.

Examples:

• "My progressed chart for today, born 1990-03-15 15:45 Riga" -> { natal_datetime: "1990-03-15T15:45", natal_timezone: "Europe/Riga" } (target_datetime defaults to now)

Returns progressed positions and the aspects progressed bodies make to natal bodies. The progressed Moon (~1 sign per 2.5 years) and progressed Sun (~1° per year) carry the most interpretive weight.

Compute the cross-chart aspects between two people's natal charts — the classic relationship-compatibility technique. Every aspect from person A's bodies/points to person B's is returned, along with both sets of positions.

Locations are not needed: synastry aspects depend only on planetary positions. (House overlays would need both birth locations — compute the two natal charts separately for that.)

Example:

• { datetime_a: "1990-03-15T15:45", timezone_a: "Europe/Riga", datetime_b: "1992-07-22T08:30", timezone_b: "America/New_York" }

Compute a midpoint composite chart for two people: a single chart describing the relationship itself, built from the shorter-arc midpoints of the two natal charts' positions and angles.

Both birth locations are required (the composite angles derive from each chart's Ascendant/Midheaven).

Example:

• { datetime_a: "1990-03-15T15:45", timezone_a: "Europe/Riga", latitude_a: 56.95, longitude_a: 24.11, datetime_b: "1992-07-22T08:30", timezone_b: "America/New_York", latitude_b: 40.71, longitude_b: -74.01 }

Find the exact moments a body returns to its natal longitude — solar returns (the astrological "birthday", one per year), lunar returns (one per ~27.3 days), or any planetary return (e.g. Saturn return, one per ~29.5 years).

Examples:

• "My solar return in 2026, born 1990-03-15 15:45 Riga" -> { body: "Sun", natal_datetime: "1990-03-15T15:45", natal_timezone: "Europe/Riga", from_datetime: "2026-01-01", to_datetime: "2027-01-01" }

• "When is my Saturn return?" -> body: "Saturn" with a multi-year window around ages 27–31.

To cast the full chart for a return moment, pass the returned datetime to compute_natal_chart with the person's current location.

Moon phase at a moment: phase angle, common name (e.g. "Waxing Gibbous"), illuminated fraction, the Moon's sign, and the next four quarter events (new moon, first quarter, full moon, last quarter) with exact times.

Example:

• "What's the moon phase tonight, and when is the next full moon?" -> {} (datetime defaults to now)

Find lunar and solar eclipses in a date range (max 30 years), with the sign and longitude of the eclipsed luminary — the astrologically relevant datum.

When latitude/longitude are provided, each solar eclipse also reports whether it is visible from that location and how much of the Sun is obscured there.

Examples:

• "Eclipses in 2026" -> { from_datetime: "2026-01-01", to_datetime: "2027-01-01" }

• "Will I see the August 2026 eclipse from Riga?" -> add latitude: 56.95, longitude: 24.11

Find a planet's retrograde periods in a date range: exact station-retrograde and station-direct moments, with the longitude and sign at each end. Periods overlapping the range edges are included whole.

Examples:

• "When is Mercury retrograde in 2026?" -> { body: "Mercury", from_datetime: "2026-01-01", to_datetime: "2027-01-01" }

The Sun and Moon never retrograde and are rejected.

Find when a body crosses sign boundaries in a date range. Retrograde crossings (backing into the previous sign) are flagged. The Sun's Aries ingress is the March equinox; Sun ingresses mark the astrological "seasons".

Examples:

• "When does Saturn change signs in the next 3 years?" -> { body: "Saturn", from_datetime: "2026-01-01", to_datetime: "2029-01-01" }

• "When does the Sun enter Aries in 2027?" -> body: "Sun", window covering March 2027

Find the exact moments a transiting body perfects an aspect to a natal position — "when exactly does Saturn square my Sun?" Retrograde loops produce multiple hits (typically three) and each is returned.

The natal position can be given two ways:

1. natal_datetime (+ natal_timezone) and natal_body — computed for you

2. natal_longitude directly, if already known

Examples:

• "When does transiting Saturn square my natal Sun (born 1990-03-15 15:45 Riga)?" -> { transiting_body: "Saturn", aspect: "square", natal_datetime: "1990-03-15T15:45", natal_timezone: "Europe/Riga", natal_body: "Sun", from_datetime: "2026-01-01", to_datetime: "2030-01-01" }