nrel-spa/.wiki/API-Reference.md

API Reference

Functions

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

Computes solar position for the given date and location. Returns raw numerical values.

Parameters:

Parameter	Type	Required	Description
date	Date	Yes	UTC date and time. Uses UTC components internally.
latitude	number	Yes	Observer latitude, -90 to 90. Negative = south.
longitude	number	Yes	Observer longitude, -180 to 180. Negative = west.
timezone	number | null	No	Hours from UTC (e.g., -4 for EDT). Default: 0.
options	SpaOptions | null	No	Atmospheric and calculation parameters.
angles	[number, ...number[]]	No	One or more custom zenith angles in degrees. See Twilight Calculations.

Returns: SpaResult

interface SpaResult {
  zenith:    number; // topocentric zenith angle (degrees)
  azimuth:   number; // topocentric azimuth, eastward from north (degrees)
  sunrise:   number; // local sunrise (fractional hours, e.g. 5.417 = 05:25)
  solarNoon: number; // local solar noon (fractional hours)
  sunset:    number; // local sunset (fractional hours)
}

sunrise, solarNoon, and sunset are NaN when options.function is SPA_ZA or SPA_ZA_INC (those codes skip the rise/set calculation).

When angles is provided, returns SpaResultWithAngles:

interface SpaResultWithAngles extends SpaResult {
  angles: SpaAnglesResult[];
}

interface SpaAnglesResult {
  sunrise: number; // rise time for this zenith angle (fractional hours)
  sunset:  number; // set time for this zenith angle (fractional hours)
}

Throws:

• TypeError if date is not a valid Date, or latitude/longitude are not finite numbers
• RangeError if latitude is outside [-90, 90] or longitude outside [-180, 180]
• RangeError if options.function is not 0, 1, 2, or 3
• RangeError if angles is provided with a non-RTS function code (SPA_ZA or SPA_ZA_INC)
• Error if the internal SPA calculation returns a non-zero error code

---

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

Same parameters as getSpa(). Formats sunrise, solarNoon, and sunset as HH:MM:SS strings.

Returns: SpaFormattedResult

interface SpaFormattedResult {
  zenith:    number; // same as SpaResult
  azimuth:   number; // same as SpaResult
  sunrise:   string; // "HH:MM:SS" or "N/A" during polar day/night, or when using SPA_ZA/SPA_ZA_INC
  solarNoon: string; // "HH:MM:SS" or "N/A"
  sunset:    string; // "HH:MM:SS" or "N/A"
}

When angles is provided, returns SpaFormattedResultWithAngles:

interface SpaFormattedResultWithAngles extends SpaFormattedResult {
  angles: SpaFormattedAnglesResult[];
}

interface SpaFormattedAnglesResult {
  sunrise: string; // "HH:MM:SS" or "N/A"
  sunset:  string; // "HH:MM:SS" or "N/A"
}

---

formatTime(hours)

Converts a fractional hour value to HH:MM:SS format.

formatTime(5.417489)  // "05:25:03"
formatTime(12)        // "12:00:00"
formatTime(23.9997)   // "23:59:59"
formatTime(-1)        // "N/A"
formatTime(NaN)       // "N/A"
formatTime(Infinity)  // "N/A"

---

SpaOptions

All options are optional. Defaults match the NREL C reference implementation.

Option	Type	Default	Description
elevation	number	0	Observer elevation above sea level in meters.
pressure	number	1013	Annual average atmospheric pressure in millibars.
temperature	number	15	Annual average temperature in degrees Celsius.
delta_ut1	number	0	Fractional second difference between UTC and UT1. Valid range: (-1, 1).
delta_t	number	67	Difference between Terrestrial Time and UTC in seconds.
slope	number	0	Surface slope from horizontal in degrees. Used for incidence angle (SPA_ZA_INC, SPA_ALL).
azm_rotation	number	0	Surface azimuth rotation from south in degrees.
atmos_refract	number	0.5667	Atmospheric refraction at sunrise/sunset in 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';

Constant	Value	Outputs Computed
SPA_ZA	0	zenith, azimuth
SPA_ZA_INC	1	zenith, azimuth, incidence angle (for solar panels on sloped surfaces)
SPA_ZA_RTS	2	zenith, azimuth, sunrise, solarNoon, sunset
SPA_ALL	3	All outputs from SPA_ZA_INC and SPA_ZA_RTS combined

The default is SPA_ZA_RTS. Use SPA_ZA for zenith/azimuth-only calculations if you do not need rise/set times; it skips the three-day calculation that rise/set requires and is slightly faster. Custom zenith angles require SPA_ZA_RTS or SPA_ALL.

---

SpaFunctionCode Type

type SpaFunctionCode = 0 | 1 | 2 | 3;

---

Named Types

All interfaces and types are exported from nrel-spa and can be imported in TypeScript:

import type {
  SpaOptions,
  SpaResult,
  SpaFormattedResult,
  SpaAnglesResult,
  SpaFormattedAnglesResult,
  SpaResultWithAngles,
  SpaFormattedResultWithAngles,
  SpaFunctionCode,
} from 'nrel-spa';

---

Home . Architecture . Twilight Calculations . NREL SPA Algorithm