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

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.