You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 7-8.RSVP
Socket
Socket
Sign inDemoInstall

@hebcal/noaa

Package Overview
Dependencies
0
Maintainers
1
Versions
15
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@hebcal/noaa

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


Version published
Maintainers
1
Created

Readme

Source

@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.

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.

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.

ParamTypeDescription
namestringThe location name for display use such as "Lakewood, NJ"
latitudenumberthe 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.
longitudenumberdouble 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.
elevationnumberthe elevation above sea level in Meters. Elevation is not used in most algorithms used for calculating sunrise and set.
timeZoneIdstringthe 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

ParamTypeDescription
elevationnumberThe 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

ParamTypeDescription
namestring | nullThe 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

ParamTypeDescription
timeZoneIdstringThe 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.

ParamTypeDescription
geoLocationGeoLocationThe location information used for calculating astronomical sun times.
dateTemporal.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.

ParamTypeDescription
offsetZenithnumberthe 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.

ParamTypeDescription
offsetZenithnumberthe 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.

ParamTypeDescription
zenithnumberthe 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
ParamTypeDescription
zenithnumberthe 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

ParamTypeDescription
zenithnumberthe 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
ParamTypeDescription
zenithnumberthe 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

elevationAdjustment = Math.toDegrees(Math.acos(earthRadiusInMeters / (earthRadiusInMeters + elevationMeters)));

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:

elevationAdjustment = 0.0347 * Math.sqrt(elevationMeters);

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

ParamTypeDescription
elevationnumberelevation 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

ParamTypeDescription
zenithnumberthe 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.
elevationnumberelevation 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.

ParamDescription
dateUsed to calculate day of year.
geoLocationThe location information used for astronomical calculating sun times.
zeniththe 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.
adjustForElevationShould 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.

ParamDescription
dateUsed to calculate day of year.
geoLocationThe location information used for astronomical calculating sun times.
zeniththe 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.
adjustForElevationShould 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()

ParamTypeDescription
startOfDayTemporal.ZonedDateTime | nullThe start of the day.
endOfDayTemporal.ZonedDateTime | nullThe 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.

ParamTypeDescription
startOfDayTemporal.ZonedDateTime | nullthe 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.
endOfDayTemporal.ZonedDateTime | nullthe 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

ParamTypeDescription
timenumberThe time to be set as the time for the Date. The time expected is in the format: 18.75 for 6:45:00 PM.
isSunrisebooleantrue 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

ParamTypeDescription
timeTemporal.ZonedDateTime | nullthe start time
offsetnumberthe 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

ParamTypeDescription
dateTemporal.ZonedDateTimetime of calculation
latnumberlatitude of location for calculation
lonnumberlongitude 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

ParamTypeDescription
dateTemporal.ZonedDateTimetime of calculation
latitudenumberlatitude of location for calculation
lonnumberlongitude of location for calculation

Keywords

FAQs

Package last updated on 26 Apr 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc