Astronomical Seasons

This package calculates the astronomical season for a given date or year.

Astronomical seasons are based around natural rotation of the Earth around the sun. Each season begins with either a solstice or an equinox, and which season those represent depends on which side of the equator you're on. Learn more about astronomical and meteorological (month-based) seasons here.

Features

• Get the current season of a date
• Get the date and time of the solstice/equinox in a month, which marks the beginning of a season
  • As a UTC datetime
  • As a Julian Day
• Get a list of all the solstices and equinoxes in a given year, which mark the beginning of a new season

Installation

yarn add @postlight/seasons

# or

npm install @postlight/seasons

Usage

The package can be called using import or required, and has been built for both CommonJS and ECMAScript module formats.

Below example demonstrates how to get the current season of a date.

import { getCurrentSeason } from "@postlight/seasons";

const currentSeason = getCurrentSeason(new Date());
console.log(currentSeason);

Functions

getCurrentSeason(date, isNorthernHemisphere?)

Gets the name of the current season for the date. Since season names are different in each hemisphere, "isNorthernHemisphere" is an optional argument and defaults to true. The season is determined on the local timezone, since the UTC date must be converted to a timezone since some solstices and equinoxes are different dates (ex: December 2023).

This function returns "spring", "summer", "winter", or "fall"

getSeasonStart(monthIndex, year)

Gets the next upcoming equinox or solstice, which is the start of the astronomical season. This returns the date and time in UTC, and it needs to be converted to the local datetime to get the correct season start date.

Example usage to get the December solstice in 2023 for EST timezone:

// Get start of winter in northern hemisphere for EST timezone
seasons.getSeasonStart(11, 2023).toLocaleString("en-US", {
  timeZone: "America/New_York",
});

// Should output: 12/21/2023, 10:28:45 PM

const utcSeasonStart = seasons.getSeasonStart(11, 2023); // result: 2023-12-22T03:28:45.400Z

// Convert UTC season start date to local season start date
const localStart = new Date(
  utcSeasonStart.getFullYear(),
  utcSeasonStart.getMonth(),
  utcSeasonStart.getDate()
);

// If local is EST timezone, should output: 2023-12-21T05:00:00.000Z

getSeasons(year) Returns a list of all the seasons in a year as UTC dates. These dates will need to be converted to the local datetime to get the correct season start date.

Result format: [march-equinox, june-solstice, september-equinox, december-solstice]

getSeasonStartJulianDay(monthIndex, year)

Returns the upcoming solstice or equinox for a month and year as a Julian Day.

getDateFromJulianDay(julianDay: number)

Converts a Julian day into a UTC date.

Sources

Below are sources that were used to create this astronomical season calculator.

• Astronomical Algorithms by Jean Meeus, 2nd edition

• US Navy Julian Date Converter

License

Licensed under either of the below, at your preference:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

🔬 A Labs project from your friends at Postlight. Happy coding!