# API Reference — Almanac

See Almanac Computation for a guide to using these routines to search for the times of sunrise, sunset, and the phases of the moon.

skyfield.almanac.find_risings(observer, target, start_time, end_time, horizon_degrees=None)

  Return the times at which a target rises above the eastern horizon.

  Given an observer on the Earth’s surface, a target like the Sun or Moon or a planet, and start and stop `Time` objects, this returns two arrays that have the same length. The first is a `Time` listing the moments at which the target rises. The second array has `True` for each time the target really crosses the horizon, and `False` when the target merely transits without actually touching the horizon.

  See Risings and settings for examples, and Computing your own refraction angle for how to use the `horizon_degrees` argument.

  Added in version 1.47.

skyfield.almanac.find_settings(observer, target, start_time, end_time, horizon_degrees=None)

  Return the times at which a target sets below the western horizon.

  Given an observer on the Earth’s surface, a target like the Sun or Moon or a planet, and start and stop `Time` objects, this returns two arrays that have the same length. The first is a `Time` listing the moments at which the target sets. The second array has `True` for each time the target really crosses the horizon, and `False` when the target merely transits without actually touching the horizon.

  See Risings and settings for examples, and Computing your own refraction angle for how to use the `horizon_degrees` argument.

  Added in version 1.47.

skyfield.almanac.find_transits(observer, target, start_time, end_time)

  Return the times at which a target transits across the meridian.

  Given an observer on the Earth’s surface, a target like the Sun or Moon or a planet, and start and stop `Time` objects, this returns a `Time` array listing the moments at which the target transits across the meridian.

  See Meridian Transits for example code.

  Added in version 1.47.

skyfield.almanac.find_discrete(start_time, end_time, f, epsilon=1.1574074074074074e-08, num=12)

  Find the times at which a discrete function of time changes value.

  This routine is used to find instantaneous events like sunrise, transits, and the seasons. See Searching for the dates of astronomical events for how to use it yourself.

skyfield.almanac.seasons(ephemeris)

  Build a function of time that returns the quarter of the year.

  The function that this returns will expect a single argument that is a `Time` and will return 0 through 3 for the seasons Spring, Summer, Autumn, and Winter.

skyfield.almanac.moon_phase(ephemeris, t)

  Return the Moon phase 0°–360° at time `t`, where 180° is Full Moon.

  More precisely: this returns an `Angle` giving the difference between the geocentric apparent ecliptic longitudes of the Moon and Sun, constrained to the interval 0°–360° (0–𝜏 radians) where 0° is New Moon and 180° is Full Moon.

skyfield.almanac.moon_phases(ephemeris)

  Build a function of time that returns the moon phase 0 through 3.

  The function that this returns will expect a single argument that is a `Time` and will return the phase of the moon as an integer. See the accompanying array `MOON_PHASES` if you want to give string names to each phase.

skyfield.almanac.moon_nodes(ephemeris)

  Build a function of time that identifies lunar nodes.

  This returns a function taking a `Time` and returning `True` if the Moon is above the ecliptic else `False`. See Lunar Nodes for how to use this routine.

skyfield.almanac.oppositions_conjunctions(ephemeris, target)

  Build a function to find oppositions and conjunctions with the Sun.

  See Opposition and Conjunction for how to call this routine and interpret the results.

skyfield.almanac.meridian_transits(ephemeris, target, topos)

  Build a function of time for finding when a body transits the meridian.

  The returned function accepts a `Time` argument and returns `True` if the `target` body is west of the observer’s meridian at that time, and otherwise returns `False.` See Meridian Transits for how to use this to search for a body’s meridian transits and antimeridian transits.

skyfield.almanac.sunrise_sunset(ephemeris, topos)

  Build a function of time that returns whether the Sun is up.

  The function that is returned will expect a single argument that is a `Time`, and will return `True` if the sun is up, else `False`.

  Skyfield uses the same definition as the United States Naval Observatory: the Sun is up when its center is 0.8333 degrees below the horizon, which accounts for both its apparent radius of around 16 arcminutes and also for the 34 arcminutes by which atmospheric refraction on average lifts the image of the Sun.

  If you need to provide a custom value for refraction, adjust the estimate of the Sun’s radius, or account for a vantage point above the Earth’s surface, see Risings and settings to learn about the more versatile `risings_and_settings()` routine.

skyfield.almanac.dark_twilight_day(ephemeris, topos)

  Build a function of time returning whether it is dark, twilight, or day.

  The function that this returns will expect a single argument that is a `Time` and will return:

  0 — Dark of night.
  1 — Astronomical twilight.
  2 — Nautical twilight.
  3 — Civil twilight.
  4 — Sun is up.

skyfield.almanac.risings_and_settings(ephemeris, target, topos, horizon_degrees=-0.5666666666666667, radius_degrees=0)

  Build a function of time that returns whether a body is up.

  This returns a function taking a `Time` argument returning `True` if the body’s altazimuth altitude angle plus `radius_degrees` is greater than `horizon_degrees`, else `False`. See Risings and settings to learn about how to search for risings and settings, and to see more about using the parameters `horizon_degrees` and `radius_degrees`.

skyfield.eclipselib.lunar_eclipses(start_time, end_time, eph)

  Return the lunar eclipses between `start_time` and `end_time`.

  Returns a three-item tuple:

  - A `Time` giving the dates of each eclipse.

  - An integer array of codes identifying how complete each eclipse is.

  - A dictionary of further supplementary details about each eclipse.

  This routine is adapted from the Explanatory Supplement to the Astronomical Almanac 11.2.3. See Lunar eclipses for the details of how to call this function.

skyfield.almanac.phase_angle(ephemeris, body, t)

  Deprecated since version 1.42: Use the `phase_angle()` position method instead.

skyfield.almanac.fraction_illuminated(ephemeris, body, t)

  Deprecated since version 1.42: Use the `fraction_illuminated()` position method instead.