class

SunTimes::SunTime

Inherits Reference < Object

Constants

CORRECTION_ECCENTRICITY = 0.00534

CORRECTION_OBLIQUITY = 0.00692

DAILY_MOTION = 0.98564736

DEG2RAD = Math::PI / 180.0

EARTH_PERIHELION_LONG = 102.9373

EQUATION_CENTER_COEFF_1 = 1.9148

Equation of center coefficients (Meeus 1998)

EQUATION_CENTER_COEFF_2 = 0.0200

EQUATION_CENTER_COEFF_3 = 0.0003

JULIAN_BASE_OFFSET = 1524.5

JULIAN_EPOCH_J2000 = 2451545.0

JULIAN_EPOCH_OFFSET = 4716

JULIAN_MONTH_FACTOR = 30.6001

JULIAN_NOON_OFFSET = 0.5

JULIAN_UNIX_EPOCH = 2440587.5

JULIAN_YEAR_DAYS = 365.25

MEAN_ANOMALY_AT_EPOCH = 357.5291

OBLIQUITY = 23.43929111

RAD2DEG = 180.0 / Math::PI

SECONDS_PER_DAY = 86400.0

SUN_ALTITUDE_ASTRONOMICAL = -18.0

SUN_ALTITUDE_CIVIL = -6.0

SUN_ALTITUDE_NAUTICAL = -12.0

SUN_ALTITUDE_RISE_SET = -0.8333

Constructors

new(latitude : Float64, longitude : Float64)

Initializes a SunTime calculator for the given latitude and longitude.

latitude - Degrees north (negative for south) longitude - Degrees east (negative for west)

Example:

SunTimes::SunTime.new(48.87, 2.67)   # Paris
SunTimes::SunTime.new({48.87, 2.67}) # Paris

Source

new(coords : Tuple(Float64, Float64))

Initializes a SunTime calculator for the given latitude and longitude.

latitude - Degrees north (negative for south) longitude - Degrees east (negative for west)

Example:

SunTimes::SunTime.new(48.87, 2.67)   # Paris
SunTimes::SunTime.new({48.87, 2.67}) # Paris

Source

Instance methods

astronomical_dawn(date : Time, location : Time::Location | Nil = nil) : Time

Returns the time of astronomical dawn (beginning of astronomical twilight). Astronomical twilight occurs when the sun is 18° below the horizon. During this period, the sky is dark enough for astronomical observations.

Arguments:

date - Time (date portion is used; time of day ignored)
location - Optional Time::Location for local conversion

Returns: Time in UTC or converted to the provided location.

Raises: CalculationError if there is no astronomical dawn (polar night or polar day).

Example:

sun.astronomical_dawn(Time.local(2025, 11, 2), paris)
=> 2025-11-02 06:37:00 UTC

Source

astronomical_dawn?(date : Time, location : Time::Location | Nil = nil) : Time | Nil

Source

astronomical_dusk(date : Time, location : Time::Location | Nil = nil) : Time

Returns the time of astronomical dusk (end of astronomical twilight).

See astronomical_dawn for details about astronomical twilight.

Source

astronomical_dusk?(date : Time, location : Time::Location | Nil = nil) : Time | Nil

Source

civil_dawn(date : Time, location : Time::Location | Nil = nil) : Time

Returns the time of civil dawn (beginning of civil twilight). Civil twilight occurs when the sun is 6° below the horizon. During this period, there is enough light for most outdoor activities.

Arguments:

date - Time (date portion is used; time of day ignored)
location - Optional Time::Location for local conversion

Returns:

Time in UTC or converted to the provided location.

Raises:

CalculationError if there is no civil dawn (polar night or polar day).

Example:

sun.civil_dawn(Time.local(2025, 11, 2), paris)
=> 2025-11-02 06:37:00 UTC

Source

civil_dawn?(date : Time, location : Time::Location | Nil = nil) : Time | Nil

Source

civil_dusk(date : Time, location : Time::Location | Nil = nil) : Time

Returns the time of civil dusk (end of civil twilight).

See civil_dawn for details about civil twilight.

Source

civil_dusk?(date : Time, location : Time::Location | Nil = nil) : Time | Nil

Source

daylight_length(date : Time, location : Time::Location | Nil = nil) : Time::Span

Returns the duration of daylight (time between sunrise and sunset) for the given date and location.

Arguments:

date - Time (only date portion is used)
location - Optional Time::Location for local conversion

Returns:

Time::Span representing total daylight duration.

Returns Time::Span.zero if there is no sunrise/sunset (polar night or polar day).

Example:

sun.daylight_length(Time.local(2025, 11, 2), paris)
=> 9 hours, 50 minutes (approx)

Source

events(date : Time, location : Time::Location | Nil = nil)

Returns all solar events for the given date and location as a NamedTuple.

Arguments:

date - Time (only date portion is used)
location - Optional Time::Location for local conversion

Returns:

NamedTuple with all solar events:

astronomical_dawn - Time?
nautical_dawn - Time?
civil_dawn - Time?
sunrise - Time?
solar_noon - Time (always available)
sunset - Time?
civil_dusk - Time?
nautical_dusk - Time?
astronomical_dusk - Time?

Example:

sun.events(Time.local(2025, 11, 2), paris)
=> {astronomical_dawn: ..., nautical_dawn: ..., ...}

Source

latitude

Source

longitude

Source

nautical_dawn(date : Time, location : Time::Location | Nil = nil) : Time

Returns the time of nautical dawn (beginning of nautical twilight). Nautical twilight occurs when the sun is 12° below the horizon. During this period, the horizon is still visible for navigation.

Arguments:

date - Time (date portion is used; time of day ignored)
location - Optional Time::Location for local conversion

Returns:

Time in UTC or converted to the provided location.

Raises:

CalculationError if there is no nautical dawn (polar night or polar day).

Example:

sun.nautical_dawn(Time.local(2025, 11, 2), paris)
=> 2025-11-02 06:37:00 UTC

Source

nautical_dawn?(date : Time, location : Time::Location | Nil = nil) : Time | Nil

Source

nautical_dusk(date : Time, location : Time::Location | Nil = nil) : Time

Returns the time of nautical dusk (end of nautical twilight). See nautical_dawn for details about nautical twilight.

Source

nautical_dusk?(date : Time, location : Time::Location | Nil = nil) : Time | Nil

Source

solar_noon(date : Time, location : Time::Location | Nil = nil) : Time

Returns the UTC or local time of solar noon (Sun's highest point) for the given date.

Solar noon corresponds to the moment when the Sun crosses the local meridian. This method uses the same underlying model as sunrise/sunset calculations.

Arguments:

date - Time (only the date portion is used)
location - Optional Time::Location for local conversion

Returns:

Time of local solar noon (UTC by default)

Example:

sun.solar_noon(Time.local(2025, 11, 2), paris)
=> 2025-11-02 12:32:50 +01:00

Source

sunrise(date : Time, location : Time::Location | Nil = nil) : Time

Returns the UTC time of sunrise for the given date.

Arguments:

date - Time (date portion is used; time of day ignored)
location - Optional Time::Location for local conversion

Returns:

Time in UTC or converted to the provided location.

Raises:

CalculationError if there is no sunrise (polar night or polar day).

Example:

sun.sunrise(Time.local(2025, 11, 2))
=> 2025-11-02 06:37:00 UTC

Source

sunrise?(date : Time, location : Time::Location | Nil = nil) : Time | Nil

Non-raising convenience variants that return nil when the event does not occur.

Source

sunset(date : Time, location : Time::Location | Nil = nil) : Time

Returns the UTC time of sunset for the given date.

Arguments and behavior are identical to #sunrise.

Raises:

CalculationError if there is no sunset (polar night or polar day).

Example:

sun.sunset(Time.local(2025, 11, 2))
=> 2025-11-02 16:47:00 UTC

Source

sunset?(date : Time, location : Time::Location | Nil = nil) : Time | Nil

Source