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](Twilight-Calculations). |

**Returns:** `SpaResult`

```typescript
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`:

```typescript
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`

```typescript
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`:

```typescript
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.

```javascript
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

```javascript
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

```typescript
type SpaFunctionCode = 0 | 1 | 2 | 3;
```

---

## Named Types

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

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

---

[Home](Home) . [Architecture](Architecture) . [Twilight Calculations](Twilight-Calculations) . [NREL SPA Algorithm](NREL-SPA-Algorithm)