nrel-spa-dart/.github/wiki/API-Reference.md

API Reference

getSpa

SpaResult getSpa(
  DateTime date,
  double latitude,
  double longitude,
  double timezone, {
  double elevation = 0,
  double pressure = 1013,
  double temperature = 15,
  double deltaUt1 = 0,
  double deltaT = 67,
  double slope = 0,
  double azmRotation = 0,
  double atmosRefract = 0.5667,
  int functionCode = spaZaRts,
  List<double> customAngles = const [],
})

Computes solar position for a given location and moment. Returns raw fractional-hour values.

Throws ArgumentError if any input falls outside the NREL SPA valid range.

Parameters

Parameter	Type	Default	Description
date	DateTime	required	UTC date and time
latitude	double	required	Degrees (-90 to 90, south negative)
longitude	double	required	Degrees (-180 to 180, west negative)
timezone	double	required	Hours from UTC (e.g., -5 for EST)
elevation	double	0	Meters above sea level
pressure	double	1013	Atmospheric pressure (mbar)
temperature	double	15	Temperature (Celsius)
deltaUt1	double	0	Difference UT1 - UTC (seconds, typically small)
deltaT	double	67	TT - UT1 (seconds)
slope	double	0	Surface tilt angle (degrees, for incidence)
azmRotation	double	0	Surface azimuth rotation (degrees, for incidence)
atmosRefract	double	0.5667	Atmospheric refraction at horizon (degrees)
functionCode	int	spaZaRts	What to calculate; one of spaZa, spaZaInc, spaZaRts, spaAll
customAngles	List<double>	[]	Zenith angles for custom rise/set computation

Function codes

Constant	Value	Computes
spaZa	0	Zenith and azimuth only
spaZaInc	1	Zenith, azimuth, and surface incidence
spaZaRts	2	Zenith, azimuth, sunrise, sunset, solar noon (default)
spaAll	3	All of the above

SpaResult fields

Field	Type	Description
zenith	double	Solar zenith angle (degrees)
azimuth	double	Solar azimuth angle, eastward from north (degrees)
sunrise	double	Sunrise in fractional hours, local time (NaN if polar)
solarNoon	double	Solar noon in fractional hours, local time (NaN if polar)
sunset	double	Sunset in fractional hours, local time (NaN if polar)
incidence	double	Surface incidence angle (degrees; spaZaInc/spaAll only)
angles	List<SpaAnglesResult>	Rise/set pairs for each entry in customAngles

SpaAnglesResult fields

Field	Type	Description
sunrise	double	Rise time in fractional hours for this zenith angle
sunset	double	Set time in fractional hours for this zenith angle

---

calcSpa

SpaFormattedResult calcSpa(
  DateTime date,
  double latitude,
  double longitude,
  double timezone, {
  // same optional parameters as getSpa
})

Same as getSpa, but formats sunrise, solarNoon, and sunset as HH:MM:SS strings. Returns "N/A" for those fields during polar day or polar night.

SpaFormattedResult fields

Field	Type	Description
zenith	double	Solar zenith angle (degrees)
azimuth	double	Solar azimuth angle (degrees)
sunrise	String	Sunrise as HH:MM:SS, or "N/A"
solarNoon	String	Solar noon as HH:MM:SS, or "N/A"
sunset	String	Sunset as HH:MM:SS, or "N/A"
incidence	double	Surface incidence angle (degrees)
angles	List<SpaFormattedAnglesResult>	Rise/set pairs with formatted strings

---

formatTime

String formatTime(double hours)

Formats fractional hours to an HH:MM:SS string. Returns "N/A" for non-finite or negative values (polar scenarios).

---

Custom zenith angles

Pass any solar zenith angles to customAngles to get rise/set times at those depression depths. Standard angles: civil twilight = 96°, nautical = 102°, astronomical = 108°. Prayer time implementations use this for Fajr and Isha.

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

for (int i = 0; i < result.angles.length; i++) {
  print('Angle ${i}: rise ${result.angles[i].sunrise}, set ${result.angles[i].sunset}');
}

---

Home