nrel_spa

NREL Solar Position Algorithm for Dart and Flutter. Calculates solar zenith, azimuth, sunrise, sunset, and solar noon for any location and time. Pure Dart, zero dependencies.

Based on Reda & Andreas (2004), NREL/TP-560-34302. Accurate to ±0.0003 degrees.

Installation

dependencies:
  nrel_spa: ^1.0.0

Dates: a day or a moment

getSpa answers two different kinds of question, and they do not want the same input.

You want	Depends on	Pass
zenith, azimuth, incidence	the exact moment	a DateTime
sunrise, solarNoon, sunset, customAngles	the calendar day only	'YYYY-MM-DD'

Rise, transit and set are independent of the time of day: hold the date and vary the hour from 00 to 23 and all three are identical to six decimal places. So for those, what matters is only which day you meant.

A DateTime cannot reliably say. toUtc() discards the author's frame in favour of the instant, so DateTime(2026, 8, 22) is 2026-08-21T15:00Z in Tokyo and a Tokyo caller gets the previous day's sunrise, 59 seconds out, silently.

getSpa('2026-08-22', lat, lng, tz);          // a day. same answer on every machine
getSpa(DateTime.now(), lat, lng, tz);        // a moment. correct for position
getSpa(DateTime(2026, 8, 22), lat, lng, tz); // ambiguous — avoid for rise/set

The string form is anchored at UTC noon and matches the TypeScript nrel-spa package exactly.

Polar day and polar night

Sunrise and sunset genuinely stop occurring above the polar circles. On those days sunrise and sunset come back as double.nan, and the formatted API renders "N/A".

solarNoon is always available. The sun crosses the local meridian every day everywhere on Earth, so solar transit is defined even when that crossing happens below the horizon, as it does throughout polar night.

The NREL reference signals "no such event" with the magic number -99999. That value never crosses this package's public API: it is finite, so it passes isFinite checks unnoticed and renders as a real clock time. The internal port stays faithful to the reference; the boundary converts it.

Quick Start

import 'package:nrel_spa/nrel_spa.dart';

void main() {
  final result = getSpa(
    DateTime.utc(2024, 3, 15, 17, 0, 0),
    40.7128,   // latitude (NYC)
    -74.0060,  // longitude
    -5.0,      // UTC offset (EST)
  );

  print('Zenith:     ${result.zenith.toStringAsFixed(4)}°');
  print('Azimuth:    ${result.azimuth.toStringAsFixed(4)}°');
  print('Sunrise:    ${result.sunrise.toStringAsFixed(4)} h');
  print('Solar Noon: ${result.solarNoon.toStringAsFixed(4)} h');
  print('Sunset:     ${result.sunset.toStringAsFixed(4)} h');
}

Custom Zenith Angles

Calculate rise/set times for any solar depression angle (twilight, prayer times, etc.):

final result = getSpa(
  DateTime.utc(2024, 3, 15, 12, 0, 0),
  40.7128, -74.0060, -5.0,
  customAngles: [96.0, 102.0, 108.0], // civil, nautical, astronomical
);

for (final angle in result.angles) {
  print('Rise: ${angle.sunrise}, Set: ${angle.sunset}');
}

API

getSpa(date, latitude, longitude, timezone, {...}) returns SpaResult with zenith, azimuth, sunrise, solarNoon, sunset, and angles. Use calcSpa for pre-formatted HH:MM:SS strings.

Full parameter reference and type definitions: API Reference.

Compatibility

Dart SDK 3.7.0+. Works in Flutter, Dart CLI, and server-side Dart. Zero dependencies.

Related

• pray_calc_dart - Islamic prayer times (uses nrel_spa)
• nrel-spa - JavaScript/TypeScript version (npm)

Acknowledgments

Reda, I. and Andreas, A. (2004). Solar Position Algorithm for Solar Radiation Applications. NREL/TP-560-34302. DOI: 10.2172/15003974

License

MIT. See LICENSE for NREL third-party notice.