Tools

Seven tools — five form the keyless, offline, deterministic core (always registered); two are network-backed extensions that register only when their config gate is enabled.

This server computes geometry — where a body is, when an event happens — not astrophysics. The core wraps astronomy-engine (sub-arcminute accuracy, ≈1900–2100), so given the same (body, time, observer) every core tool returns identical output with no network, no rate limit, and no API key. It does not geocode: resolve a place name to latitude/longitude upstream (e.g. via an OpenStreetMap server) and pass an IANA timezone to receive observer-local times alongside UTC.

astronomy_get_sky_position

Apparent topocentric position of one solar-system body or a named bright star.

• Equatorial (RA/Dec), refraction-corrected horizontal (altitude/azimuth), and ecliptic coordinates in one call
• Distance, apparent magnitude, angular diameter, phase angle, illuminated fraction, and the constellation the body falls in
• Parallax- and aberration-corrected for the observer; default elevation 0 m, default time now
• Supply star (e.g. "Sirius", "Polaris") instead of body to target a catalog star; star takes precedence over body
• null magnitude / angular diameter / phase fields where the engine cannot compute them — never fabricated

astronomy_get_rise_set

Rise, set, and culmination times, with twilight for the Sun.

• Searches forward from start and returns the next count cycles (default 1, max 31)
• For body: "sun", bundles the three twilight pairs (civil −6°, nautical −12°, astronomical −18°) so a single call answers "when does the sun set and when is it truly dark"
• Circumpolar / never-rises situations are reported as null rise/set fields with an explanatory note rather than an error — the fact is the answer
• Optional observer-local times when an IANA timezone is supplied

astronomy_find_events

Forward search across nine event classes under one event enum.

• solar_eclipse, lunar_eclipse, equinox, solstice, moon_quarter, opposition, conjunction, max_elongation, perigee_apogee
• Solar eclipses require an observer (latitude/longitude) and report local visibility and contact times; lunar eclipses are geocentric and need no location
• The body-relative events (opposition, conjunction, max_elongation, perigee_apogee) require a body, gated to the bodies each event exists for: opposition to the superior planets (mars through pluto), conjunction to any planet, max_elongation to mercury and venus, perigee_apogee to the moon, earth, or a planet
• perigee_apogee on earth returns its perihelion and aphelion; conjunction on mercury or venus returns both the inferior and superior passes, labelled by conjunction_kind
• Returns the next count occurrences (default 1, max 20)

astronomy_list_visible

The workflow flagship — one call returns a ranked, condition-gated "what's up" list.

• Iterates every naked-eye solar-system body (and, with include_stars, the bundled bright stars), keeps those above the horizon, and ranks them brightest-and-highest first
• Attaches a plain-language visibility_note to each body, computed from real magnitude and altitude — no synthetic score
• Returns the whole-sky condition (daylight / civil_twilight / nautical_twilight / astronomical_twilight / dark) and the Sun's altitude alongside the list
• time is a single evaluation instant, not a window — for "tonight" pass a time after astronomical dusk (use astronomy_get_rise_set on the Sun to find it)
• Use min_altitude to skip objects grazing the horizon

astronomy_get_ephemeris (gated extension)

Time-series ephemeris for a small body or spacecraft via the keyless JPL Horizons API. Registered only when ASTRONOMY_ENABLE_HORIZONS is set.

• Covers asteroids, comets, and spacecraft the in-process major-body engine cannot see
• The designation is passed to Horizons verbatim and must resolve to a single record:
  • Numbered asteroid — trailing-semicolon record lookup: "433;" (Eros), "1;" (Ceres)
  • Periodic comet — DES + closest-apparition flag: "DES=1P;CAP" (Halley), "DES=2P;CAP" (Encke)
  • Spacecraft — negative SPK-ID: "-48" (Hubble)
  • A bare name like "433 Eros" or "1P/Halley" returns no match or an ambiguous record list and is rejected. Look up designations at ssd.jpl.nasa.gov/tools/sbdb_lookup.html.
• start/stop are ISO 8601 UTC and stop must be after start; step is a positive count plus a unit of m, h, d, mo, or y ("10m", "1h", "1d")
• Supplying observer latitude/longitude yields topocentric coordinates and adds alt/az — pass both or neither; one alone is rejected rather than silently downgraded to a geocentric query. Horizons is asked for refracted elevation on a topocentric request, so altitude_degrees carries the same refraction correction the offline core tools report
• Large spans truncate inline at 200 rows. The disclosure names the instant the returned rows end at and the start to resume from — one step past it, because Horizons includes the start instant in its output, so resuming at the last row returned repeats it. Re-call with that start, or split the range into smaller adjacent spans — keep the same step and repeat until truncated is false, which concatenates back into the original series with no repeated sample. Widening the step discards samples the original range asked for

astronomy_get_satellite_passes (gated extension)

Visible passes of a satellite over an observer. Registered only when ASTRONOMY_ENABLE_SATELLITES is set.