nrel-spa-dart/.github/wiki/guides/quickstart.md

Quickstart

Install

Add to pubspec.yaml:

dependencies:
  nrel_spa: ^1.0.1

Run dart pub get.

First Call

import 'package:nrel_spa/nrel_spa.dart';

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

  print('Solar zenith:  ${result.zenith.toStringAsFixed(4)}°');
  print('Solar 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');
}

Reading Results

getSpa returns an SpaResult:

Field	Type	Description
zenith	double	Solar zenith angle (degrees)
azimuth	double	Solar azimuth angle (degrees from north)
sunrise	double	Sunrise time (decimal hours, UTC)
solarNoon	double	Solar noon time (decimal hours, UTC)
sunset	double	Sunset time (decimal hours, UTC)
angles	List<AngleResult>	Rise/set times for custom zenith angles

DateTime Input

Always pass UTC DateTime values. The timezone parameter shifts the output times to local time.

// Convert local DateTime to UTC before passing
final local = DateTime(2024, 3, 15, 12, 0, 0);
final utc = local.toUtc();
final result = getSpa(utc, lat, lng, utcOffset);

Null Results for Sunrise/Sunset

At polar latitudes or in summer/winter extremes, sunrise or sunset may not occur. In those cases, result.sunrise and result.sunset return double.nan. Always check before displaying:

if (!result.sunrise.isNaN) {
  print('Sunrise: ${result.sunrise}');
} else {
  print('No sunrise today.');
}