A tiny library to get the exact date and time in an ISO 8601 format for certain points of the day for any desired location and date.

Install

npm install suntimes

Api Reference

Functions

getDeclinationOfTheSun(date) ⇒ number

The angular distance of the sun north or south of the earth's equator.

Kind: global function Returns: number - The declination in degrees where north is a positive value and south is a negative value within a range of range of -23.45 and 23.45.

| Param | Type | Description | | ----- | ----------------- | --------------- | | date | Date | A date instance |

Example (Example usage of getDeclinationOfTheSun)

// returns -23.078780854838076
getDeclinationOfTheSun(new Date(2019, 0, 1));

equationOfTime(date) ⇒ number

The correction between standard clock time and the time based on the exact position of the sun in the sky represented as decimal time in minutes.

Kind: global function Returns: number - A number whose value is the equation of time in minutes decimal time for the Date represented by date.

| Param | Type | Description | | ----- | ----------------- | ---------------- | | date | Date | A date instance. |

Example (Example usage of equationOfTime)

// returns -10.306964615344999
equationOfTime(new Date(2025, 0, 18));

getHourAngleSinceNoon(date, latitude, angle) ⇒ number

Gets the hour angle difference between noon and the angle value.

Kind: global function Returns: number - A number whose value represents the hour angle since noon for the date, latitude and angle value. Throws:

• RangeError The sun altitude never elevates above the angle specified.
• RangeError The sun altitude never drops below the angle specified.

| Param | Type | Description | | -------- | ------------------- | ------------------------------------------- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | angle | number | An angle value. |

Example (Example usage of getHourAngleSinceNoon)

// returns 5.54554469317797
getHourAngleSinceNoon(new Date(2025, 0, 18), 51.477730, -12);

getNoonHourAngle(date, longitude) ⇒ number

Gets the noon hour angle for the date and longitude value.

Kind: global function Returns: number - The noon hour angle expressed as a number between 0.00 and 23.9.

| Param | Type | Description | | --------- | ------------------- | ---------------------------------------------- | | date | Date | A date instance. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getNoonHourAngle)

// returns 12.17245941025575
getNoonHourAngle(new Date(2025, 0, 18), -0.010150);

getNoonDateTimeUtc(date, longitude) ⇒ string

Gets the noon date and time in UTC expressed in an ISO 8601 format for date and longitude value.

Kind: global function Returns: string - A string representing noon date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --------- | ------------------- | ---------------------------------------------- | | date | Date | A date instance. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getNoonDateTimeUtc)

// returns "2025-01-18T12:10:20.853Z"
getNoonDateTimeUtc(new Date(2025, 0, 18), -0.010150);

getDateTimeUtcOfAngleBeforeNoon(angle, date, latitude, longitude) ⇒ string

Gets the date and time in UTC expressed in an ISO 8601 format for an angle before noon for the angle, date, latitude and longitude value.

Kind: global function Returns: string - A string representing the time and date for an angle before noon in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --------- | ------------------- | ---------------------------------------------- | | angle | number | An angle value. | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getDateTimeUtcOfAngleBeforeNoon)

// returns "2025-01-18T05:57:45.720Z"
getDateTimeUtcOfAngleBeforeNoon(-18, new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getDateTimeUtcOfAngleBeforeNoon)

// returns "The sun's altitude does not drop to -18° on Wed Jun 18 2025 at latitude 51.47773 and longitude -0.01015"
getDateTimeUtcOfAngleBeforeNoon(-18, new Date(2025, 5, 18), 51.477730, -0.010150);

Example (Example usage of getDateTimeUtcOfAngleBeforeNoon)

// returns "The sun's altitude does not rise to 18° on Wed Jun 18 2025 at latitude -51.47773 and longitude -0.01015"
getDateTimeUtcOfAngleBeforeNoon(18, new Date(2025, 5, 18), -51.477730, -0.010150);

getDateTimeUtcOfAngleAfterNoon(angle, date, latitude, longitude) ⇒ string

Gets the date and time in UTC expressed in an ISO 8601 format for an angle after noon for the angle, date, latitude and longitude value. Kind: global function Returns: string - A string representing the time and date for an angle after noon in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --------- | ------------------- | ---------------------------------------------- | | angle | number | An angle value. | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getDateTimeUtcOfAngleAfterNoon)

//returns "2025-06-18T14:33:42.689Z"
getDateTimeUtcOfAngleAfterNoon(8, new Date(2025, 5, 18), -51.477730, -0.010150);

Example (Example usage of getDateTimeUtcOfAngleAfterNoon)

// returns "The sun's altitude does not drop to -18° on Sat Jan 18 2025 at latitude -51.47773 and longitude -0.01015"
getDateTimeUtcOfAngleAfterNoon(-18, new Date(2025, 0, 18), -51.477730, -0.010150);

Example (Example usage of getDateTimeUtcOfAngleAfterNoon)

// returns "The sun's altitude does not rise to 18° on Wed Jun 18 2025 at latitude -51.47773 and longitude -0.01015"
getDateTimeUtcOfAngleAfterNoon(18, new Date(2025, 5, 18), -51.477730, -0.010150);

getSunriseDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the sunrise date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing sunrise date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --------- | ------------------- | ---------------------------------------------- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getSunriseDateTimeUtc)

// returns "2025-01-18T07:57:29.802Z"
getSunriseDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getSunriseDateTimeUtc)

// returns "The sun is up all day on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getSunriseDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

Example (Example usage of getSunriseDateTimeUtc)

// returns "The sun is down all day on Thu Jan 01 2032 at latitude 89.525 and longitude -30.45"
getSunriseDateTimeUtc(new Date(2032, 0, 1), 89.5250, -30.4500);

getSunsetDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the sunset date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing sunset date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getSunsetDateTimeUtc)

// returns "2025-01-18T16:23:11.903Z"
getSunsetDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getSunsetDateTimeUtc)

// returns "The sun is up all day on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getSunsetDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

Example (Example usage of getSunsetDateTimeUtc)

// returns "The sun is down all day on Thu Jan 01 2032 at latitude 89.525 and longitude -30.45"
getSunsetDateTimeUtc(new Date(2032, 0, 1), 89.5250, -30.4500);

getCivilDawnEndDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the end of civil dawn date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the end of civil dawn date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getCivilDawnEndDateTimeUtc)

// returns "2025-01-18T07:57:29.802Z"
getCivilDawnEndDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getCivilDawnEndDateTimeUtc)

// returns "The sun is up all day on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getCivilDawnEndDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

Example (Example usage of getCivilDawnEndDateTimeUtc)

// returns "The sun is down all day on Thu Jan 01 2032 at latitude 89.525 and longitude -30.45
getCivilDawnEndDateTimeUtc(new Date(2032, 0, 1), 89.5250, -30.4500);

getCivilDawnStartDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the start of civil dawn date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the start of civil dawn date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getCivilDawnStartDateTimeUtc)

// returns "2025-01-18T07:19:15.781Z"
getCivilDawnStartDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getCivilDawnStartDateTimeUtc)

// returns "The sun's altitude does not rise to -6° on Thu Jan 01 2032 at latitude 89.525 and longitude -30.45"
getCivilDawnStartDateTimeUtc(new Date(2032, 0, 1), 89.5250, -30.4500);

Example (Example usage of getCivilDawnStartDateTimeUtc)

// returns "The sun's altitude does not drop to -6° on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getCivilDawnStartDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

getNauticalDawnEndDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the end of nautical dawn date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the end of nautical dawn date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getNauticalDawnEndDateTimeUtc)

// returns "2025-01-18T07:19:15.781Z"
getNauticalDawnEndDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getNauticalDawnEndDateTimeUtc)

// returns "The sun's altitude does not rise to -6° on Thu Jan 01 2032 at latitude 89.525 and longitude -30.45"
getNauticalDawnEndDateTimeUtc(new Date(2032, 0, 1), 89.5250, -30.4500);

Example (Example usage of getNauticalDawnEndDateTimeUtc)

// returns "The sun's altitude does not drop to -6° on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getNauticalDawnEndDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

getNauticalDawnStartDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the start of nautical dawn date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the start of nautical dawn date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getNauticalDawnStartDateTimeUtc)

// returns "2025-01-18T06:37:36.892Z"
getNauticalDawnStartDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getNauticalDawnStartDateTimeUtc)

// returns "The sun's altitude does not drop to -12° on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getNauticalDawnStartDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

Example (Example usage of getNauticalDawnStartDateTimeUtc)

// returns "The sun's altitude does not rise to -12° on Thu Jan 01 2032 at latitude 89.525 and longitude -30.45"
getNauticalDawnStartDateTimeUtc(new Date(2032, 0, 1), 89.5250, -30.4500);

getAstronomicalDawnEndDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the end of astronomical dawn date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the end of astronomical dawn date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getAstronomicalDawnEndDateTimeUtc)

// returns "2025-01-18T06:37:36.892Z"
getAstronomicalDawnEndDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getAstronomicalDawnEndDateTimeUtc)

// returns "The sun's altitude does not drop to -12° on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getAstronomicalDawnEndDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

getAstronomicalDawnStartDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the start of astronomical dawn date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the start of astronomical dawn date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getAstronomicalDawnStartDateTimeUtc)

// returns "2025-01-18T05:57:45.720Z"
getAstronomicalDawnStartDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getAstronomicalDawnStartDateTimeUtc)

// returns "The sun's altitude does not drop to -18° on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getAstronomicalDawnStartDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

getAstronomicalDuskStartDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the start of astronomical dusk date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the start of astronomical dusk date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getAstronomicalDuskStartDateTimeUtc)

// returns "2025-01-18T17:43:04.813Z"
getAstronomicalDuskStartDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getAstronomicalDuskStartDateTimeUtc)

// returns "The sun's altitude does not drop to -12° on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getAstronomicalDuskStartDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

getAstronomicalDuskEndDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the end of astronomical dusk date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the end of astronomical dusk date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getAstronomicalDuskEndDateTimeUtc)

// returns "2025-01-18T18:22:55.985Z"
getAstronomicalDuskEndDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getAstronomicalDuskEndDateTimeUtc)

// returns "The sun's altitude does not drop to -18° on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getAstronomicalDuskEndDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

getNauticalDuskEndDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the end of nautical dusk date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the end of nautical dusk date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getNauticalDuskEndDateTimeUtc)

// returns "2025-01-18T17:43:04.813Z"
getNauticalDuskEndDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getNauticalDuskEndDateTimeUtc)

// returns The sun's altitude does not rise to -12° on Thu Jan 01 2032 at latitude 89.525 and longitude -30.45
getNauticalDuskEndDateTimeUtc(new Date(2032, 0, 1), 89.5250, -30.4500);

Example (Example usage of getNauticalDuskEndDateTimeUtc)

// returns "The sun's altitude does not drop to -12° on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getNauticalDuskEndDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

getNauticalDuskStartDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the start of nautical dusk date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the start of nautical dusk date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getNauticalDuskStartDateTimeUtc)

// returns "2025-01-18T17:01:25.924Z"
getNauticalDuskStartDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getNauticalDuskStartDateTimeUtc)

// returns The sun's altitude does not rise to -6° on Thu Jan 01 2032 at latitude 89.525 and longitude -30.45
getNauticalDuskStartDateTimeUtc(new Date(2032, 0, 1), 89.5250, -30.4500);

Example (Example usage of getNauticalDuskStartDateTimeUtc)

// returns "The sun's altitude does not drop to -6° on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getNauticalDuskStartDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

getCivilDuskEndDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the end of civil dusk date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the end of civil dusk date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getCivilDuskEndDateTimeUtc)

// returns "2025-01-18T17:01:25.924Z"
getCivilDuskEndDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getCivilDuskEndDateTimeUtc)

returns "The sun's altitude does not drop to -6° on Wed Jun 18 2025 at  latitude -75.100620 and longitude 123.354750"
getCivilDuskEndDateTimeUtc(new Date(2002, 0, 27), -75.100620, 123.354750);

Example (Example usage of getNauticalDuskEndDateTimeUtc)

// returns The sun's altitude does not rise to -6° on Thu Jan 01 2032 at latitude 89.525 and longitude -30.45
getCivilDuskEndDateTimeUtc(new Date(2032, 0, 1), 89.5250, -30.4500);

getCivilDuskStartDateTimeUtc(date, latitude, longitude) ⇒ string

Gets the start of civil dusk date and time in UTC expressed in an ISO 8601 format for date instance, latitude and longitude value.

Kind: global function Returns: string - A string representing the start of civil dusk date and time in UTC, expressed in an ISO 8601 format.

| Param | Type | Description | | --- | --- | --- | | date | Date | A date instance. | | latitude | number | A latitude value in the range of -90 to 90. | | longitude | number | A longitude value in the range of -180 to 180. |

Example (Example usage of getCivilDuskStartDateTimeUtc)

// returns "2025-01-18T16:23:11.903Z"
getCivilDuskStartDateTimeUtc(new Date(2025, 0, 18), 51.477730, -0.010150);

Example (Example usage of getCivilDuskStartDateTimeUtc)

returns "The sun's altitude does not rise to -6° on Wed Jun 18 2025 at  latitude -75.100620 and longitude 123.354750"
getCivilDuskStartDateTimeUtc(new Date(2002, 0, 27), -75.100620, 123.354750);

Example (Example usage of getCivilDuskStartDateTimeUtc)

// returns "The sun is up all day on Sun Aug 02 2037 at latitude 71.98007 and longitude 102.47427"
getCivilDuskStartDateTimeUtc(new Date(2037, 7, 2), 71.980070, 102.474270);

Example (Example usage of getCivilDuskStartDateTimeUtc)

// returns "The sun is down all day on Thu Jan 01 2032 at latitude 89.525 and longitude -30.45"
getCivilDuskStartDateTimeUtc(new Date(2032, 0, 1), 89.5250, -30.4500);