nrel-spa

Pure JavaScript implementation of the NREL Solar Position Algorithm (SPA). Computes solar zenith angle, azimuth, sunrise, sunset, and solar noon for any location and date. Validated to produce identical results to the original NREL C reference implementation.

Installation

npm install nrel-spa

Quick Start

import { getSpa, calcSpa } from 'nrel-spa';

const date = new Date('2025-06-21T00:00:00Z'); // UTC date/time

// Minimum required parameters
const raw = getSpa(date, 40.7128, -74.006, -4); // New York, EDT (UTC-4)
console.log(raw.sunrise);   // 5.417 (fractional hours)
console.log(raw.solarNoon); // 12.965
console.log(raw.sunset);    // 20.509

// Formatted output — same parameters, HH:MM:SS strings
const fmt = calcSpa(date, 40.7128, -74.006, -4);
console.log(fmt.sunrise);   // "05:25:03"
console.log(fmt.solarNoon); // "12:57:56"
console.log(fmt.sunset);    // "20:30:35"

// With atmospheric parameters and custom zenith angles (twilight)
const result = calcSpa(
  date,
  40.7128,          // latitude (degrees, negative = south)
  -74.006,          // longitude (degrees, negative = west)
  -4,               // timezone offset in hours from UTC
  {
    elevation: 10,  // meters above sea level
    pressure: 1013, // millibars
    temperature: 20 // degrees Celsius
  },
  [96, 102, 108],   // civil, nautical, astronomical twilight zenith angles
);
console.log(result.sunrise);        // "05:25:03"
console.log(result.angles[0]);      // { sunrise: "04:53:...", sunset: "20:02:..." }

API

getSpa(date, latitude, longitude, timezone?, options?, angles?)

Returns raw numerical values. Sunrise, solarNoon, and sunset are fractional hours (e.g., 5.417 for 05:25).

| Parameter | Type | Required | Description | | --- | --- | --- | --- | | date | Date | Yes | UTC date and time for the calculation | | latitude | number | Yes | Observer latitude in degrees (-90 to 90) | | longitude | number | Yes | Observer longitude in degrees (-180 to 180) | | timezone | number \| null | No | Hours from UTC. Default: 0 | | options | SpaOptions \| null | No | Atmospheric and calculation parameters | | angles | number[] | No | Custom zenith angles in degrees for twilight |

Returns: SpaResult (or SpaResultWithAngles when angles is provided)

interface SpaResult {
  zenith:    number; // topocentric zenith angle (degrees)
  azimuth:   number; // topocentric azimuth, eastward from north (degrees)
  sunrise:   number; // local sunrise time (fractional hours)
  solarNoon: number; // local solar noon (fractional hours)
  sunset:    number; // local sunset time (fractional hours)
}

calcSpa(date, latitude, longitude, timezone?, options?, angles?)

Same as getSpa(), but formats sunrise, solarNoon, and sunset as HH:MM:SS strings. Returns "N/A" for those fields during polar day or polar night.

formatTime(hours)

Converts fractional hours to HH:MM:SS format. Returns "N/A" for negative or non-finite values.

import { formatTime } from 'nrel-spa';
formatTime(5.417489); // "05:25:03"
formatTime(-1);       // "N/A"

SpaOptions

| Option | Type | Default | Description | | --- | --- | --- | --- | | elevation | number | 0 | Observer elevation in meters | | pressure | number | 1013 | Atmospheric pressure in millibars | | temperature | number | 15 | Temperature in degrees Celsius | | delta_ut1 | number | 0 | UT1-UTC correction in seconds | | delta_t | number | 67 | TT-UTC difference in seconds | | slope | number | 0 | Surface slope from horizontal (degrees) | | azm_rotation | number | 0 | Surface azimuth rotation from south (degrees) | | atmos_refract | number | 0.5667 | Atmospheric refraction at sunrise/sunset (degrees) | | function | SpaFunctionCode | SPA_ZA_RTS | Which outputs to compute |

Function Codes

import { SPA_ZA, SPA_ZA_INC, SPA_ZA_RTS, SPA_ALL } from 'nrel-spa';

| Code | Value | Computes | | --- | --- | --- | | SPA_ZA | 0 | Zenith and azimuth only | | SPA_ZA_INC | 1 | Zenith, azimuth, and incidence angle | | SPA_ZA_RTS | 2 | Zenith, azimuth, sunrise, noon, sunset (default) | | SPA_ALL | 3 | All outputs |

Architecture

The core algorithm in lib/spa.js is a direct port of the NREL SPA C source to JavaScript, preserving the same mathematical structure: 63 periodic nutation terms, full heliocentric coordinate calculation, topocentric correction, and atmospheric refraction. It has been validated to produce output identical to the C reference within rounding.

The TypeScript wrapper in src/ provides the public API, input validation, and the formatTime utility. The package ships dual CJS and ESM builds via tsup, with full TypeScript definitions.

See the wiki for a detailed breakdown of the algorithm and architecture.

Compatibility

• Node.js: 20, 22, 24 (CI tested)
• ESM: import { getSpa } from 'nrel-spa'
• CommonJS: const { getSpa } = require('nrel-spa')
• TypeScript: Full type definitions included

Bundlers (Vite, Webpack, esbuild, Rollup) work via the exports map in package.json.

TypeScript

import {
  getSpa,
  calcSpa,
  formatTime,
  SPA_ZA,
  SPA_ZA_INC,
  SPA_ZA_RTS,
  SPA_ALL,
  type SpaOptions,
  type SpaResult,
  type SpaFormattedResult,
  type SpaAnglesResult,
  type SpaFormattedAnglesResult,
  type SpaResultWithAngles,
  type SpaFormattedResultWithAngles,
  type SpaFunctionCode,
} from 'nrel-spa';

Documentation

Full documentation is available on the GitHub Wiki:

• API Reference
• Architecture
• Twilight Calculations
• NREL SPA Algorithm

Related

Other packages in this collection:

• solar-spa: WASM build of the same algorithm, async, for high-throughput batch calculations
• pray-calc: Islamic prayer times built on nrel-spa

Acknowledgments

The core algorithm is a JavaScript port of the Solar Position Algorithm (SPA) developed by Ibrahim Reda and Afshin Andreas at the National Renewable Energy Laboratory (NREL):

Reda, I., Andreas, A. (2004). "Solar Position Algorithm for Solar Radiation Applications." Solar Energy, 76(5), 577-589. https://doi.org/10.1016/j.solener.2003.12.003

Original source: https://midcdmz.nrel.gov/spa/

License

MIT (TypeScript wrapper and build tooling). The core algorithm in lib/spa.js is a port of NREL's SPA C source, which is subject to its own terms. See the LICENSE file for the full notice.