npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@hebcal/noaa

v0.8.14

Published

sunrise and sunset via NOAA algorithm with elevation, based on KosherJava

Downloads

3,480

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

mjradwinmjradwin

Keywords

zmanimzmankosherzmanimkosher-zmanimkosherjava

Readme

@hebcal/noaa

sunrise and sunset via NOAA algorithm with elevation, based on KosherJava

Introduction

This is a fork/subset of KosherZmanim library with Temporal replacing usage of Luxon.

Kosher Zmanim itself is a TS/JS port of the KosherJava library.

Installation

$ npm install @hebcal/noaa

Classes

GeoLocation

A class that contains location information such as latitude and longitude required for astronomical calculations. The elevation field may not be used by some calculation engines and would be ignored if set.

Kind: global class
Version: 1.1
Author: © Eliyahu Hershfeld 2004 - 2016

new GeoLocation(name, latitude, longitude, elevation, timeZoneId)

GeoLocation constructor with parameters for all required fields.

| Param | Type | Description | | --- | --- | --- | | name | string | The location name for display use such as "Lakewood, NJ" | | latitude | number | the latitude in a double format such as 40.095965 for Lakewood, NJ. Note: For latitudes south of the equator, a negative value should be used. | | longitude | number | double the longitude in a double format such as -74.222130 for Lakewood, NJ. Note: For longitudes west of the Prime Meridian (Greenwich), a negative value should be used. | | elevation | number | the elevation above sea level in Meters. Elevation is not used in most algorithms used for calculating sunrise and set. | | timeZoneId | string | the TimeZone for the location. |

geoLocation.getElevation() ⇒ number

Method to get the elevation in Meters.

Kind: instance method of GeoLocation
Returns: number - Returns the elevation in Meters.

geoLocation.setElevation(elevation)

Method to set the elevation in Meters above sea level.

Kind: instance method of GeoLocation

| Param | Type | Description | | --- | --- | --- | | elevation | number | The elevation to set in Meters. An Error will be thrown if the value is a negative. |

geoLocation.getLatitude() ⇒ number

Kind: instance method of GeoLocation
Returns: number - Returns the latitude.

geoLocation.getLongitude() ⇒ number

Kind: instance method of GeoLocation
Returns: number - Returns the longitude.

geoLocation.getLocationName() ⇒ string | null

Kind: instance method of GeoLocation
Returns: string | null - Returns the location name.

geoLocation.setLocationName(name)

Kind: instance method of GeoLocation

| Param | Type | Description | | --- | --- | --- | | name | string | null | The setter method for the display name. |

geoLocation.getTimeZone() ⇒ string

Kind: instance method of GeoLocation
Returns: string - Returns the timeZone.

geoLocation.setTimeZone(timeZoneId)

Method to set the TimeZone.

Kind: instance method of GeoLocation

| Param | Type | Description | | --- | --- | --- | | timeZoneId | string | The timeZone to set. |

NOAACalculator

Implementation of sunrise and sunset methods to calculate astronomical times based on the NOAA algorithm. This calculator uses the Java algorithm based on the implementation by NOAA - National Oceanic and Atmospheric Administration's Surface Radiation Research Branch. NOAA's implementation is based on equations from Astronomical Algorithms by Jean Meeus. Added to the algorithm is an adjustment of the zenith to account for elevation. The algorithm can be found in the Wikipedia Sunrise Equation article.

Kind: global class
Author: © Eliyahu Hershfeld 2011 - 2019

new NOAACalculator(geoLocation, date)

A constructor that takes in geolocation information as a parameter.

| Param | Type | Description | | --- | --- | --- | | geoLocation | GeoLocation | The location information used for calculating astronomical sun times. | | date | Temporal.PlainDate | |

noaaCalculator.getSunrise() ⇒ Temporal.ZonedDateTime | null

The getSunrise method Returns a Date representing the elevation adjusted sunrise time. The zenith used for the calculation uses geometric zenith of 90° plus getElevationAdjustment. This is adjusted to add approximately 50/60 of a degree to account for 34 archminutes of refraction and 16 archminutes for the sun's radius for a total of 90.83333°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - the Date representing the exact sunrise time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

  • adjustZenith
  • getSeaLevelSunrise()
  • getUTCSunrise

noaaCalculator.getSeaLevelSunrise() ⇒ Temporal.ZonedDateTime | null

A method that returns the sunrise without elevation adjustment. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns sunrise calculated at sea level. This forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - the Date representing the exact sea-level sunrise time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

  • getSunrise
  • getUTCSeaLevelSunrise
  • getSeaLevelSunset()

noaaCalculator.getBeginCivilTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the beginning of civil twilight (dawn) using a zenith of 96°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the beginning of civil twilight using a zenith of 96°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: CIVIL_ZENITH

noaaCalculator.getBeginNauticalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the beginning of nautical twilight using a zenith of 102°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the beginning of nautical twilight using a zenith of 102°. If the calculation can't be computed null will be returned. See detailed explanation on top of the page.
See: NAUTICAL_ZENITH

noaaCalculator.getBeginAstronomicalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the beginning of astronomical twilight using a zenith of 108°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the beginning of astronomical twilight using a zenith of 108°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: ASTRONOMICAL_ZENITH

noaaCalculator.getSunset() ⇒ Temporal.ZonedDateTime | null

The getSunset method Returns a Date representing the elevation adjusted sunset time. The zenith used for the calculation uses geometric zenith of 90° plus getElevationAdjustment. This is adjusted to add approximately 50/60 of a degree to account for 34 archminutes of refraction and 16 archminutes for the sun's radius for a total of 90.83333°. Note: In certain cases the calculates sunset will occur before sunrise. This will typically happen when a timezone other than the local timezone is used (calculating Los Angeles sunset using a GMT timezone for example). In this case the sunset date will be incremented to the following date.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date representing the exact sunset time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

  • adjustZenith
  • getSeaLevelSunset()
  • getUTCSunset

noaaCalculator.getSeaLevelSunset() ⇒ Temporal.ZonedDateTime | null

A method that returns the sunset without elevation adjustment. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns sunset calculated at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after sunset.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date representing the exact sea-level sunset time. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.
See

  • getSunset
  • getUTCSeaLevelSunset

noaaCalculator.getEndCivilTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the end of civil twilight using a zenith of 96°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the end of civil twilight using a zenith of 96°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: CIVIL_ZENITH

noaaCalculator.getEndNauticalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the end of nautical twilight using a zenith of 102°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the end of nautical twilight using a zenith of 102° . If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: NAUTICAL_ZENITH

noaaCalculator.getEndAstronomicalTwilight() ⇒ Temporal.ZonedDateTime | null

A method that returns the end of astronomical twilight using a zenith of 108°.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the end of astronomical twilight using a zenith of 108°. If the calculation can't be computed, null will be returned. See detailed explanation on top of the page.
See: ASTRONOMICAL_ZENITH

noaaCalculator.getSunriseOffsetByDegrees(offsetZenith) ⇒ Temporal.ZonedDateTime | null

A utility method that returns the time of an offset by degrees below or above the horizon of sunrise. Note that the degree offset is from the vertical, so for a calculation of 14° before sunrise, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date of the offset after (or before) getSunrise. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.

| Param | Type | Description | | --- | --- | --- | | offsetZenith | number | the degrees before getSunrise to use in the calculation. For time after sunrise use negative numbers. Note that the degree offset is from the vertical, so for a calculation of 14° before sunrise, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter. |

noaaCalculator.getSunsetOffsetByDegrees(offsetZenith) ⇒ Temporal.ZonedDateTime | null

A utility method that returns the time of an offset by degrees below or above the horizon of sunset. Note that the degree offset is from the vertical, so for a calculation of 14° after sunset, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Dateof the offset after (or before) getSunset. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, a null will be returned. See detailed explanation on top of the page.

| Param | Type | Description | | --- | --- | --- | | offsetZenith | number | the degrees after getSunset to use in the calculation. For time before sunset use negative numbers. Note that the degree offset is from the vertical, so for a calculation of 14° after sunset, an offset of 14 + GEOMETRIC_ZENITH = 104 would have to be passed as a parameter. |

noaaCalculator.getUTCSunrise0(zenith) ⇒ number

A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time.

Kind: instance method of NOAACalculator
Returns: number - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, NaN will be returned. See detailed explanation on top of the page.

| Param | Type | Description | | --- | --- | --- | | zenith | number | the degrees below the horizon. For time after sunrise use negative numbers. |

noaaCalculator.getUTCSeaLevelSunrise(zenith) ⇒ number

A method that returns the sunrise in UTC time without correction for time zone offset from GMT and without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns UTC sunrise calculated at sea level. This forms the base for dawn calculations that are calculated as a dip below the horizon before sunrise.

Kind: instance method of NOAACalculator
Returns: number - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, NaN will be returned. See detailed explanation on top of the page.
See

  • getUTCSunrise
  • getUTCSeaLevelSunset

| Param | Type | Description | | --- | --- | --- | | zenith | number | the degrees below the horizon. For time after sunrise use negative numbers. |

noaaCalculator.getUTCSunset0(zenith) ⇒ number

A method that returns the sunset in UTC time without correction for time zone offset from GMT and without using daylight savings time.

Kind: instance method of NOAACalculator
Returns: number - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, NaN will be returned. See detailed explanation on top of the page.
See: getUTCSeaLevelSunset

| Param | Type | Description | | --- | --- | --- | | zenith | number | the degrees below the horizon. For time after sunset use negative numbers. |

noaaCalculator.getUTCSeaLevelSunset(zenith) ⇒ number

A method that returns the sunset in UTC time without correction for elevation, time zone offset from GMT and without using daylight savings time. Non-sunrise and sunset calculations such as dawn and dusk, depend on the amount of visible light, something that is not affected by elevation. This method returns UTC sunset calculated at sea level. This forms the base for dusk calculations that are calculated as a dip below the horizon after sunset.

Kind: instance method of NOAACalculator
Returns: number - The time in the format: 18.75 for 18:45:00 UTC/GMT. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, NaN will be returned. See detailed explanation on top of the page.
See

  • getUTCSunset
  • getUTCSeaLevelSunrise

| Param | Type | Description | | --- | --- | --- | | zenith | number | the degrees below the horizon. For time before sunset use negative numbers. |

noaaCalculator.getElevationAdjustment(elevation) ⇒ number

Method to return the adjustment to the zenith required to account for the elevation. Since a person at a higher elevation can see farther below the horizon, the calculation for sunrise / sunset is calculated below the horizon used at sea level. This is only used for sunrise and sunset and not times before or after it such as nautical twilight since those calculations are based on the level of available light at the given dip below the horizon, something that is not affected by elevation, the adjustment should only made if the zenith == 90° adjusted for refraction and solar radius. The algorithm used is

The source of this algorithm is Calendrical Calculations by Edward M. Reingold and Nachum Dershowitz. An alternate algorithm that produces an almost identical (but not accurate) result found in Ma'aglay Tzedek by Moishe Kosower and other sources is:

Kind: instance method of NOAACalculator
Returns: number - the adjusted zenith

| Param | Type | Description | | --- | --- | --- | | elevation | number | elevation in Meters. |

noaaCalculator.adjustZenith(zenith, elevation) ⇒ number

Adjusts the zenith of astronomical sunrise and sunset to account for solar refraction, solar radius and elevation. The value for Sun's zenith and true rise/set Zenith (used in this class and subclasses) is the angle that the center of the Sun makes to a line perpendicular to the Earth's surface. If the Sun were a point and the Earth were without an atmosphere, true sunset and sunrise would correspond to a 90° zenith. Because the Sun is not a point, and because the atmosphere refracts light, this 90° zenith does not, in fact, correspond to true sunset or sunrise, instead the centre of the Sun's disk must lie just below the horizon for the upper edge to be obscured. This means that a zenith of just above 90° must be used. The Sun subtends an angle of 16 minutes of arc, and atmospheric refraction accounts for 34 minutes or so, giving a total of 50 arcminutes. The total value for ZENITH is 90+(5/6) or 90.8333333° for true sunrise/sunset. Since a person at an elevation can see blow the horizon of a person at sea level, this will also adjust the zenith to account for elevation if available. Note that this will only adjust the value if the zenith is exactly 90 degrees. For values below and above this no correction is done. As an example, astronomical twilight is when the sun is 18° below the horizon or 108° below the zenith. This is traditionally calculated with none of the above mentioned adjustments. The same goes for various tzais and alos times such as the 16.1° dip used in ComplexZmanimCalendar#getAlos16Point1Degrees.

Kind: instance method of NOAACalculator
Returns: number - The zenith adjusted to include the sun's radius, refracton and elevation adjustment. This will only be adjusted for sunrise and sunset (if the zenith == 90°)
See: getElevationAdjustment

| Param | Type | Description | | --- | --- | --- | | zenith | number | the azimuth below the vertical zenith of 90°. For sunset typically the zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be getEndNauticalTwilight that passes NAUTICAL_ZENITH to this method. | | elevation | number | elevation in Meters. |

noaaCalculator.getUTCSunrise(date, geoLocation, zenith, adjustForElevation) ⇒

A method that calculates UTC sunrise as well as any time based on an angle above or below sunrise.

Kind: instance method of NOAACalculator
Returns: The UTC time of sunrise in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in the calculation (expected behavior for some locations such as near the poles, NaN will be returned.

| Param | Description | | --- | --- | | date | Used to calculate day of year. | | geoLocation | The location information used for astronomical calculating sun times. | | zenith | the azimuth below the vertical zenith of 90 degrees. for sunrise typically the zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be getBeginNauticalTwilight that passes NAUTICAL_ZENITH to this method. | | adjustForElevation | Should the time be adjusted for elevation |

noaaCalculator.getUTCSunset(date, geoLocation, zenith, adjustForElevation) ⇒

A method that calculates UTC sunset as well as any time based on an angle above or below sunset.

Kind: instance method of NOAACalculator
Returns: The UTC time of sunset in 24 hour format. 5:45:00 AM will return 5.75.0. If an error was encountered in the calculation (expected behavior for some locations such as near the poles, NaN will be returned.

| Param | Description | | --- | --- | | date | Used to calculate day of year. | | geoLocation | The location information used for astronomical calculating sun times. | | zenith | the azimuth below the vertical zenith of 90°. For sunset typically the zenith used for the calculation uses geometric zenith of 90° and adjusts this slightly to account for solar refraction and the sun's radius. Another example would be getEndNauticalTwilight that passes NAUTICAL_ZENITH to this method. | | adjustForElevation | Should the time be adjusted for elevation |

noaaCalculator.getTemporalHour(startOfDay, endOfDay) ⇒ number

A utility method that will allow the calculation of a temporal (solar) hour based on the sunrise and sunset passed as parameters to this method. An example of the use of this method would be the calculation of a non-elevation adjusted temporal hour by passing in sea level sunrise and sea level sunset as parameters.

Kind: instance method of NOAACalculator
Returns: number - the long millisecond length of the temporal hour. If the calculation can't be computed a NaN will be returned. See detailed explanation on top of the page.
See: getTemporalHour()

| Param | Type | Description | | --- | --- | --- | | startOfDay | Temporal.ZonedDateTime | null | The start of the day. | | endOfDay | Temporal.ZonedDateTime | null | The end of the day. |

noaaCalculator.getSunTransit(startOfDay, endOfDay) ⇒ Temporal.ZonedDateTime | null

A method that returns sundial or solar noon. It occurs when the Sun is transiting the celestial meridian. In this class it is calculated as halfway between the sunrise and sunset passed to this method. This time can be slightly off the real transit time due to changes in declination (the lengthening or shortening day).

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date representing Sun's transit. If the calculation can't be computed such as in the Arctic Circle where there is at least one day a year where the sun does not rise, and one where it does not set, null will be returned. See detailed explanation on top of the page.

| Param | Type | Description | | --- | --- | --- | | startOfDay | Temporal.ZonedDateTime | null | the start of day for calculating the sun's transit. This can be sea level sunrise, visual sunrise (or any arbitrary start of day) passed to this method. | | endOfDay | Temporal.ZonedDateTime | null | the end of day for calculating the sun's transit. This can be sea level sunset, visual sunset (or any arbitrary end of day) passed to this method. |

noaaCalculator.getDateFromTime(time, isSunrise) ⇒ Temporal.ZonedDateTime | null

A method that returns a Date from the time passed in as a parameter.

Kind: instance method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - The Date.
Access: protected

| Param | Type | Description | | --- | --- | --- | | time | number | The time to be set as the time for the Date. The time expected is in the format: 18.75 for 6:45:00 PM. | | isSunrise | boolean | true if the time is sunrise, and false if it is sunset |

NOAACalculator.CIVIL_ZENITH

Sun's zenith at civil twilight (96°).

Kind: static property of NOAACalculator

NOAACalculator.NAUTICAL_ZENITH

Sun's zenith at nautical twilight (102°).

Kind: static property of NOAACalculator

NOAACalculator.ASTRONOMICAL_ZENITH

Sun's zenith at astronomical twilight (108°).

Kind: static property of NOAACalculator

NOAACalculator.getTimeOffset(time, offset) ⇒ Temporal.ZonedDateTime | null

A utility method that returns a date offset by the offset time passed in. Please note that the level of light during twilight is not affected by elevation, so if this is being used to calculate an offset before sunrise or after sunset with the intent of getting a rough "level of light" calculation, the sunrise or sunset time passed to this method should be sea level sunrise and sunset.

Kind: static method of NOAACalculator
Returns: Temporal.ZonedDateTime | null - the Date with the offset in milliseconds added to it

| Param | Type | Description | | --- | --- | --- | | time | Temporal.ZonedDateTime | null | the start time | | offset | number | the offset in milliseconds to add to the time. |

NOAACalculator.getSolarElevation(date, lat, lon) ⇒ number

Return the Solar Elevation for the horizontal coordinate system at the given location at the given time. Can be negative if the sun is below the horizon. Not corrected for altitude.

Kind: static method of NOAACalculator
Returns: number - solar elevation in degrees - horizon is 0 degrees, civil twilight is -6 degrees

| Param | Type | Description | | --- | --- | --- | | date | Temporal.ZonedDateTime | time of calculation | | lat | number | latitude of location for calculation | | lon | number | longitude of location for calculation |

NOAACalculator.getSolarAzimuth(date, latitude, lon) ⇒ number

Return the Solar Azimuth for the horizontal coordinate system at the given location at the given time. Not corrected for altitude. True south is 0 degrees.

Kind: static method of NOAACalculator

| Param | Type | Description | | --- | --- | --- | | date | Temporal.ZonedDateTime | time of calculation | | latitude | number | latitude of location for calculation | | lon | number | longitude of location for calculation |