Get Earth's seasons and orbital events for a year.

Returns dates and times for equinoxes (equal day/night), solstices (longest/shortest days), and Earth's perihelion (closest to sun) and aphelion (farthest from sun).

Args: year: Year to query (1700-2100) timezone: Timezone offset from UTC in hours. If not provided, UTC (0) is used. dst: Whether to apply daylight saving time adjustment.

Returns: SeasonsResponse with equinoxes, solstices, perihelion, and aphelion.

Tips for LLMs: - Typically 6 events per year (2 equinoxes, 2 solstices, perihelion, aphelion) - Seasons are opposite in Northern and Southern hemispheres - Earth's 23.5 degree axial tilt causes seasons, not distance from sun

Example: seasons = await get_earth_seasons(2024) for event in seasons.data: print(f"{event.phenom}: {event.month}/{event.day}/{event.year} at {event.time}")

Get upcoming moon phases starting from a given date.

Returns the next N moon phase occurrences (New Moon, First Quarter, Full Moon, Last Quarter) with exact times. Useful for planning astronomical observations, photography, or understanding lunar cycles.

Args: date: Start date in YYYY-MM-DD format. No leading zeros required (e.g., "2024-1-5" is valid). Valid range: 1700-01-01 to 2100-12-31 num_phases: Number of phases to return (1-99). Default is 12 (about 3 months of phases). Each lunar cycle has 4 phases, so 12 phases = 3 complete cycles.

Returns: MoonPhasesResponse: Contains: - phasedata: List of phase occurrences with exact dates and times - Each phase includes: phase name, year, month, day, time (in UT1)

Tips for LLMs: - All times are in Universal Time (UT1), not local time - A complete lunar cycle is about 29.5 days (4 phases) - Use num_phases=4 for the next month, 12 for next quarter, 48 for next year - Moon phases are useful for: astronomy, photography (full moon lighting), fishing/hunting (activity patterns), gardening (traditional planting cycles)

Example: # Get next 12 moon phases starting from May 3, 2009 phases = await get_moon_phases("2009-5-3", num_phases=12) for phase in phases.phasedata: print(f"{phase.phase} on {phase.year}-{phase.month}-{phase.day} at {phase.time} UT")

Get rise, set, and transit times for a planet on a given day at a location.

Returns the times a planet rises above the horizon, transits the meridian (highest point), and sets below the horizon. Essential for planning when to observe a planet.

Args: planet: Planet name. One of: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto date: Date in YYYY-MM-DD format (e.g., "2025-6-15") latitude: Observer's latitude in decimal degrees (-90 to 90) longitude: Observer's longitude in decimal degrees (-180 to 180) timezone: Timezone offset from UTC in hours (e.g., -8 for PST). When provided, event times are in local time. dst: Whether to apply daylight saving time adjustment.

Returns: PlanetEventsResponse: GeoJSON Feature containing: - geometry: Observer location - properties.data: - planet: Planet name - date: Query date - events: List of rise/set/transit events with times - constellation: Current constellation - magnitude: Apparent visual magnitude - artifact_ref: Reference to stored computation (if artifact store configured)

Tips for LLMs: - Events may be empty if the planet doesn't rise/set that day (polar regions) - Transit time is when the planet is highest — best viewing time - Use with get_planet_position to get full details at a specific time - Outer planets (Jupiter, Saturn) are above the horizon for ~12 hours - Inner planets (Mercury, Venus) are only visible near sunrise or sunset

Example: events = await get_planet_events( planet="Jupiter", date="2025-6-15", latitude=51.5, longitude=-0.1, timezone=1 ) for event in events.properties.data.events: print(f"Jupiter {event.phen} at {event.time}")

Get position and observational data for a planet at a specific time and location.

Returns altitude, azimuth, distance, phase illumination, apparent magnitude, constellation, equatorial coordinates (RA/Dec), elongation from the sun, and visibility status. Essential for planning astronomical observations and answering "where is [planet] tonight?" questions.

Args: planet: Planet name. One of: Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto date: Date in YYYY-MM-DD format (e.g., "2025-6-15") time: Time in HH:MM format, 24-hour (e.g., "22:30"). Interpreted as UTC unless timezone is specified. latitude: Observer's latitude in decimal degrees (-90 to 90) longitude: Observer's longitude in decimal degrees (-180 to 180) timezone: Timezone offset from UTC in hours (e.g., -8 for PST, 1 for CET). When provided, the time parameter is interpreted as local time.

Returns: PlanetPositionResponse: GeoJSON Feature containing: - geometry: Observer location - properties.data: Planet position data: - altitude: Degrees above horizon (negative = below horizon) - azimuth: Degrees clockwise from north (0=N, 90=E, 180=S, 270=W) - distance_au / distance_km: Distance from observer - illumination: Phase illumination percentage (0-100) - magnitude: Apparent visual magnitude (lower = brighter) - constellation: IAU constellation abbreviation - right_ascension / declination: Equatorial coordinates (J2000) - elongation: Angular distance from sun in degrees - visibility: "visible", "below_horizon", or "lost_in_sunlight" - artifact_ref: Reference to stored computation (if artifact store configured)

Tips for LLMs: - Lower magnitude = brighter. Venus can reach -4.4, Jupiter -2.7 - Elongation < 10-15 degrees means planet is too close to the sun to see - altitude > 0 means the planet is above the horizon - azimuth tells you where to look: 0=North, 90=East, 180=South, 270=West - For "where is Mars tonight?", use time="21:00" with appropriate timezone - Mercury is hardest to see (small elongation), Venus and Jupiter are easiest

Example: pos = await get_planet_position( planet="Mars", date="2025-6-15", time="22:00", latitude=47.6, longitude=-122.3, timezone=-7 ) data = pos.properties.data if data.visibility == "visible": print(f"Mars is at {data.altitude}° altitude, {data.azimuth}° azimuth") print(f"Magnitude: {data.magnitude}, in {data.constellation}")

Get a complete sky summary — all planets, moon phase, and darkness — in one call.

Returns which planets are visible, their positions and brightness, the current moon phase, and whether the sky is dark enough for observation. This is the recommended tool for "what's in the sky tonight?" questions.

Args: date: Date in YYYY-MM-DD format (e.g., "2026-2-10") time: Time in HH:MM format, 24-hour (e.g., "21:00"). UTC unless timezone specified. latitude: Observer's latitude in decimal degrees (-90 to 90) longitude: Observer's longitude in decimal degrees (-180 to 180) timezone: Timezone offset from UTC in hours (e.g., 0 for GMT, -5 for EST, 1 for CET). When provided, the time parameter is interpreted as local time.

Returns: SkyResponse: GeoJSON Feature containing: - properties.data.visible_planets: Planets above horizon and not lost in sunlight, sorted brightest first. Each has altitude, azimuth, direction, magnitude, constellation, and visibility status. - properties.data.all_planets: All 8 planets regardless of visibility - properties.data.moon: Current phase and illumination percentage - properties.data.is_dark: True if sun is below -6 degrees (civil twilight) - properties.data.summary: One-line text summary for quick display

Tips for LLMs: - Use this instead of calling get_planet_position 8 times - The summary field gives a quick human-readable answer - visible_planets are sorted brightest first (lowest magnitude) - direction field gives compass bearing: "S" = look south, "NE" = northeast - is_dark=False means it's daytime or twilight — planets may not be visible even if above horizon - Combine with weather forecast to check if skies are clear enough to observe

Example: sky = await get_sky( date="2026-2-10", time="21:00", latitude=51.99, longitude=0.84, timezone=0 ) for p in sky.properties.data.visible_planets: print(f"{p.planet}: {p.direction}, magnitude {p.magnitude}, in {p.constellation}") print(sky.properties.data.summary)

Get local solar eclipse circumstances for a specific date and location.

Calculates whether a solar eclipse is visible from a given location on a specific date, and if so, provides detailed timing and positional information for all eclipse phases.

Args: date: Date of the eclipse in YYYY-MM-DD format. Valid range: 1800-01-01 to 2050-12-31 latitude: Observer's latitude in decimal degrees (-90 to 90) longitude: Observer's longitude in decimal degrees (-180 to 180) height: Observer's height above mean sea level in meters. Default is 0. Range: -200 to 10000 meters.

Returns: SolarEclipseByDateResponse: GeoJSON Feature with eclipse type, magnitude, obscuration, duration, and local circumstances.

Tips for LLMs: - If description is "No Eclipse at this Location", the eclipse isn't visible here - magnitude >= 1.0 indicates total eclipse; < 1.0 is partial - altitude must be > 0 for eclipse to be visible (sun above horizon) - Use get_solar_eclipses_by_year first to find eclipse dates

Example: eclipse = await get_solar_eclipse_by_date( date="2017-8-21", latitude=46.67, longitude=-122.65, height=15 ) print(f"Eclipse type: {eclipse.properties.description}")

Get a list of all solar eclipses occurring in a specific year.

Returns all solar eclipses (total, annular, partial, and hybrid) that occur worldwide in the specified year. Use this to find eclipse dates, then use get_solar_eclipse_by_date to get detailed local circumstances.

Args: year: Year to query (1800-2050)

Returns: SolarEclipseByYearResponse with list of eclipse events.

Tips for LLMs: - Most years have 2 solar eclipses, some have 3, rarely 4 - After finding an eclipse date, use get_solar_eclipse_by_date to check visibility

Example: eclipses = await get_solar_eclipses_by_year(2024) for eclipse in eclipses.eclipses_in_year: print(f"{eclipse.event} on {eclipse.year}-{eclipse.month}-{eclipse.day}")

Get complete sun and moon data for one day at a specific location.

Provides rise, set, and transit times for the sun and moon, twilight times, moon phase, and illumination percentage. Essential for planning outdoor activities, photography, navigation, and astronomical observations.

Args: date: Date in YYYY-MM-DD format. No leading zeros required. latitude: Latitude in decimal degrees. Range: -90 to 90 (negative = South, positive = North) longitude: Longitude in decimal degrees. Range: -180 to 180 (negative = West, positive = East) timezone: Timezone offset from UTC in hours (e.g., -8 for PST, 1 for CET). Positive = East of UTC, Negative = West of UTC. If not provided, UTC (0) is used. dst: Whether to apply daylight saving time adjustment. If not provided, defaults to false. label: Optional user label (max 20 characters) to identify this query in the response

Returns: OneDayResponse: GeoJSON Feature containing: - geometry: Location coordinates - properties.data: Complete sun and moon information: - sundata: List of sun events (rise, set, transit, civil twilight begin/end) - moondata: List of moon events (rise, set, transit) - curphase: Current moon phase description - fracillum: Percentage of moon illuminated (e.g., "92%") - closestphase: Details of the nearest moon phase

Tips for LLMs: - Times are in the requested timezone (or UTC if not specified) - sundata and moondata may be empty in polar regions during extreme seasons - Civil twilight is when the sun is 6 degrees below horizon - Use fracillum to determine moon brightness for night photography or stargazing - Moon transit time indicates when moon is highest in the sky (best viewing)

Example: data = await get_sun_moon_data( date="2005-9-20", latitude=47.60, longitude=-122.33, timezone=-8, dst=True ) sunrise = next(e for e in data.properties.data.sundata if e.phen == "Rise") print(f"Sunrise at {sunrise.time}")