io.github.thirdtrail/thirdtrail

Clear-sky Daily Light Integral in mol/m²/day for each day in a range: photosynthetically active radiation integrated from sunrise to sunset. Use it to plan crop growth or supplemental greenhouse lighting; it assumes cloudless skies, so treat it as the ceiling for the site. Pass from and to together for a range of UTC days, or neither for today. Requires an API key on a paid Solar plan.

Fajr, sunrise, dhuhr, asr, maghrib and isha for one date at a location, elevation-corrected. Use it for Islamic prayer schedules; for general sunrise, sunset and twilight use get_sun_moon_times. school is required and sets the fajr and isha rules; asr_method picks the shadow rule and defaults to shafi. date defaults to today. Requires an API key on a paid Ephemerides plan.

The sun's azimuth and altitude through one UTC day, sampled every interval: a list of timestamped positions. Use it for shading studies, PV siting and panel-angle planning; for a single instant use get_solar_position. date defaults to today and interval to 15m. Requires an API key on a paid Solar plan.

The sun's position at one instant: azimuth, altitude, zenith, declination, hour angle and equation of time, plus clear-sky irradiance (GHI, DNI and DHI in W/m²) when include asks for it and the plan covers it. Use it for where the sun is at a given moment; for its track through a whole day use get_solar_path, and for rise and set times use get_sun_moon_times. timestamp defaults to now. Positions are NREL SPA-equivalent on JPL DE421; irradiance comes from the Bird clear-sky model. Requires an API key on a paid Solar plan.

Sunrise, sunset, solar noon, civil, nautical and astronomical twilight, golden and blue hour, moonrise, moonset and moon phase for a location, one entry per day. Use it for any question about when the sun or moon rises, sets or gets dark; for the sun's angle at a given moment use get_solar_position, and for tides alongside the sun use get_tide_window. Pass elevation whenever you know it: it shifts sunrise and sunset at altitude. Defaults: from today, 7 days or the plan's limit if lower. Requires an API key on a paid Ephemerides plan.

High and low water times and heights at any coastal point, from the FES2022 global tide atlas: a list of events, each with type (high or low), time and height_m. Use it for when high or low tide is; for a continuous curve use get_tide_heights, and for tides together with sunrise, golden hour and moon phase use get_tide_window. Heights are metres relative to MEAN SEA LEVEL, not chart datum — never use for navigation. Defaults: from today, 2 days or the plan's limit if lower. Requires an API key on a paid Tides plan.

Water height at a coastal point at a fixed step: a list of time and height_m pairs. Use it to plot a tide curve or read the height at a particular time; for just the highs and lows use get_tide_extremes. Metres relative to mean sea level, not chart datum. Defaults: from today, 2 days, and the finest step the plan allows, but no finer than 10m. Requires an API key on a paid Tides plan.

Per day: high and low waters together with sunrise, sunset, golden and blue hour, twilight and moon phase in a single call. The planning tool for coastal photography, fishing and shore work; use it instead of calling get_tide_extremes and get_sun_moon_times separately. Pass elevation when you know it: it shifts the sun and moon times — roughly three minutes at clifftop height — but never the tide heights, which do not depend on where the observer stands. Defaults: from today, 2 days or the plan's limit if lower. Requires an API key on a paid Tides plan.