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.

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.