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) and Lilith (mean lunar apogee / Black Moon Lilith).

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 and Lilith, house cusps, Ascendant and Midheaven, 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), 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" }