pray-calc/.wiki/API-Reference.md

API Reference

getTimes

Compute prayer times as fractional hours.

function getTimes(
  date: Date,
  lat: number,
  lng: number,
  tz?: number,           // default: system UTC offset
  elevation?: number,    // meters above sea level, default 0
  temperature?: number,  // °C, default 15
  pressure?: number,     // mbar, default 1013.25
  hanafi?: boolean,      // Asr convention, default false (Shafi'i)
): PrayerTimes

PrayerTimes

Field	Type	Description
Qiyam	number	Start of the last third of the night (Qiyam al-Layl)
Fajr	number	True dawn (Subh Sadiq)
Sunrise	number	Astronomical sunrise
Noon	number	Solar noon (exact geometric transit)
Dhuhr	number	2.5 minutes after solar noon
Asr	number	Asr (Shafi'i or Hanafi shadow ratio)
Maghrib	number	Astronomical sunset
Isha	number	Nightfall (end of shafaq)
angles	TwilightAngles	Dynamic depression angles used

All times are fractional hours in local time (e.g., 5.5 = 05:30:00). NaN means the event cannot be computed for this date/location (polar night, etc.).

---

calcTimes

Same as getTimes but returns HH:MM:SS strings.

function calcTimes(
  date: Date,
  lat: number,
  lng: number,
  tz?: number,
  elevation?: number,
  temperature?: number,
  pressure?: number,
  hanafi?: boolean,
): FormattedPrayerTimes

Returns "N/A" for any time that cannot be computed.

---

getTimesAll

Compute the dynamic method times plus comparison times for all 14 traditional methods.

function getTimesAll(
  date: Date,
  lat: number,
  lng: number,
  tz?: number,
  elevation?: number,
  temperature?: number,
  pressure?: number,
  hanafi?: boolean,
): PrayerTimesAll

PrayerTimesAll

Extends PrayerTimes with:

Field	Type	Description
Methods	Record<string, [number, number]>	[fajrTime, ishaTime] per method ID

Method IDs: UOIF, ISNACA, ISNA, SAMR, IGUT, MWL, DIBT, Karachi, Kuwait, UAQ, Qatar, Egypt, MUIS, MSC.

---

calcTimesAll

Same as getTimesAll but returns HH:MM:SS strings.

function calcTimesAll(
  date: Date,
  lat: number,
  lng: number,
  tz?: number,
  elevation?: number,
  temperature?: number,
  pressure?: number,
  hanafi?: boolean,
): FormattedPrayerTimesAll

---

getAngles

Compute dynamic Fajr/Isha depression angles without computing full prayer times.

function getAngles(
  date: Date,
  lat: number,
  lng: number,
  elevation?: number,
  temperature?: number,
  pressure?: number,
): TwilightAngles

Returns { fajrAngle: number, ishaAngle: number } in degrees (positive = below horizon).

---

getAsr

Compute Asr time from known solar noon and solar declination.

function getAsr(
  solarNoon: number,    // fractional hours (local time)
  latitude: number,     // decimal degrees
  declination: number,  // solar declination in degrees
  hanafi?: boolean,     // default false (Shafi'i, shadowFactor=1)
): number

Returns Asr as fractional hours, or NaN if the sun never reaches the required altitude.

Shadow factors: Shafi'i = 1 (shadow equals object height), Hanafi = 2 (shadow = 2x height).

---

getQiyam

Compute start of the last third of the night.

function getQiyam(
  fajrTime: number,  // fractional hours
  ishaTime: number,  // fractional hours
): number

Returns fractional hours. The night is divided from Isha to Fajr; Qiyam starts at the 2/3 mark: ishaTime + (2/3) × (fajrTime + 24 − ishaTime).

---

getMscFajr / getMscIsha

Compute the Moonsighting Committee Worldwide seasonal time offsets.

function getMscFajr(date: Date, latitude: number): number
// Returns minutes before astronomical sunrise for Fajr

function getMscIsha(
  date: Date,
  latitude: number,
  shafaq?: ShafaqMode,  // 'general' | 'ahmer' | 'abyad', default 'general'
): number
// Returns minutes after astronomical sunset for Isha

These are the low-level functions used internally by getAngles and getTimesAll. You rarely need to call them directly.

---

solarEphemeris / toJulianDate

Jean Meeus solar ephemeris (Chapter 25 of Astronomical Algorithms, 2nd ed.).

function toJulianDate(date: Date): number

function solarEphemeris(jd: number): {
  decl: number;    // solar declination, degrees
  r: number;       // Earth-Sun distance, AU
  eclLon: number;  // apparent ecliptic longitude, degrees
}

Accuracy: declination within ~0.01°, r within ~0.0001 AU. These are used internally to drive the physics corrections in getAngles.

---

METHODS

Exported array of all 14 MethodDefinition objects for documentation/tooling use.

const METHODS: MethodDefinition[]

interface MethodDefinition {
  id: string;
  name: string;
  region: string;
  fajrAngle: number | null;
  ishaAngle: number | null;
  ishaMinutes?: number;   // UAQ and Qatar: 90 minutes after sunset
  useMSC?: boolean;       // MSC seasonal method
}

---

Types

type FractionalHours = number;
type TimeString = string;          // "HH:MM:SS" or "N/A"
type AsrConvention = 'shafii' | 'hanafi';
type ShafaqMode = 'general' | 'ahmer' | 'abyad';

interface TwilightAngles {
  fajrAngle: number;
  ishaAngle: number;
}

interface PrayerTimes { ... }          // see above
interface FormattedPrayerTimes { ... } // same fields but TimeString
interface PrayerTimesAll extends PrayerTimes { Methods: ... }
interface FormattedPrayerTimesAll { ... }
interface AtmosphericParams { elevation?, temperature?, pressure?: number }
interface MethodDefinition { ... }

---

Moon Functions (Removed in v2)

getMoon, getMoonPhase, getMoonPosition, getMoonIllumination, and getMoonVisibility were removed in v2. They now live in the dedicated moon-sighting package.

See Moon Migration for the full migration guide and function mapping.

---

Back to Home | Dynamic Algorithm | Traditional Methods