acamaratapray-calc
A high-precision prayer times calculator using NREL-SPA (Solar Position Algorithm) and a dynamic Fajr and Isha angle algorithm, refined with empirical data and machine learning. Also supports traditional static-angle methods for comparison.
Live Demo: PrayCalc.com
Documentation & Wiki: PrayCalc.net
📌 This library is in active development and is currently in beta. Please test and submit feedback or issues, inshaa’ Allah.
🚀 Version 1.7 Highlights
Version 1.7 introduces major improvements:
- ✅ Fixed a bug in the core NREL-SPA JavaScript implementation that caused times to be off by up to several minutes.
- ✅ Custom dynamic angle calculation has been completely rewritten using scientific modeling, atmospheric inputs, and ML-trained empirical data. It now generates Fajr and Isha angles that are accurate across all locations and seasons, instead of a simple offset from 18°.
Traditional calculators (based on suncalc or fixed-angle approximations) are known to have timing errors of 2–7 minutes or more, especially at higher latitudes. Our implementation aims for sub-minute accuracy by default.
📦 Installation
npm install pray-calc🛠️ Usage Example
const { getTimes, calcTimesAll } = require('pray-calc');
// Example for New York City (minimal params)
const date = new Date('2024-01-01T00:00:00Z');
const city = "New York";
const lat = 40.7128;
const lng = -74.006;
const tz = -5;
// Full example for Jakarta:
/*
const city = "Jakarta";
const lat = -6.2088;
const lng = 106.8456;
const tz = 7;
const elevation = 18;
const temperature = 26.56;
const pressure = 1017;
*/
const get = getTimes(date, lat, lng); // Minimal args
const calc = calcTimesAll(date, lat, lng, tz); // Full formatting
console.log(`\nTest: ${city} on ${date.toISOString()}:\n`);
console.log("getTimes =", get, "\n");
console.log("calcTimesAll =", calc, "\n");🔧 Functions Overview
getTimes(date, lat, lng, tz?, elevation?, temperature?, pressure?, standard?)
Returns prayer times as decimal/fractional hours using dynamic twilight angles.
calcTimesAll(date, lat, lng, tz?, elevation?, temperature?, pressure?)
Returns prayer times as formatted HH:MM:SS and includes traditional methods under a .methods key.
getMoon(date, accuracy = false)
Returns:
fraction– moon illumination (0–1)phase– moon phase (e.g., Full Moon)angle– angle from the sun (for visibility estimation)
Helpful for determining moon visibility after Maghrib.
🔢 Parameters
date: JavaScriptDateobjectlat: Latitude (decimal degrees)lng: Longitude (decimal degrees)tz: Timezone offset from UTC (optional, defaults toDateobject)elevation: Meters above sea level (default: 50)temperature: Ambient °C (default: 15)pressure: mbar / hPa (default: 1013.25)standard: true = Shāfiʿī (Asr shadow = 1), false = Ḥanafī (shadow = 2)
📚 Static vs. Dynamic Methods
The All functions return both:
- The custom dynamic method (default)
- Multiple legacy methods:
- Muslim World League (MWL)
- Egyptian General Authority of Survey (EGAS)
- ISNA, Umm al-Qura, Gulf, etc.
This lets developers compare traditional fixed-angle results to the more accurate dynamic calculation.
🤝 Contributing
Contributions, observations, and validations are welcome!
- GitHub: acamarata/pray-calc
- NREL-SPA JS Engine: acamarata/nrel-spa
🧪 Accuracy Notes
This package is built for high-precision use cases:
- Real-time applications (e.g., adhan clocks)
- Scientific Islamic astronomy
- High-latitude and seasonal edge-case handling
All core calculations use NREL-SPA and angles dynamically generated to match observable twilight.