prayer-first

# prayer-first **Accurate Islamic prayer times by city and location** A developer-focused Node.js package for retrieving Islamic prayer times based on city and country. ## 📦 Installation ```bash npm install prayer-first ``` ## Usage ### Import the library and functions #### If you're using CommonJS (require) ```js const { PrayerTimes , getPrayerTime, getPrayerTimeByCity} = require('prayer-first'); ``` #### If you're using ES Modules (import) ```js import { PrayerTimes, getPrayerTime, getPrayerTimeByCity } from 'prayer-first'; ``` ## Examples using CommonJS ### Get Prayer Times by Latitude and Longitude ```js const { getPrayerTime } = require('prayer-first'); const latitude = 36.191196; // geographical latitude of the location in decimal Ex: Erbil latitude const longitude = 44.009962; // geographical longitude of the location in decimal Ex: Erbil longitude const day = 15; const month = 8; const year = 2025; const MidNightAndLastThird = true; // optional calculation for midnight and last third of the night const result = getPrayerTime(latitude, longitude, day, month, year, MidNightAndLastThird); if (result.status) { console.log('Prayer times for:', result.city, result.country); console.log(result.times); } else { console.error('Error:', result.error); } ``` <details> <summary>result</summary> ```json { "status": true, "date": "08-15", "times": { "fajr": "03:51", "sunrise": "05:30", "dhuhr": "12:19", "asr": "15:58", "maghrib": "18:58", "isha": "20:13", "midNight": "23:24", "lastThirdStart": "00:53" }, "city": "Erbil", "country": "Iraq" } ``` </details> ### Get Prayer Times by Country and City Name ```js const { getPrayerTimeByCity } = require('prayer-first'); const countryName = 'IQ'; // Can be country Name or country Short code Ex: IQ for Iraq const cityName = 'Erbil'; // city Name Ex: Erbil const day = 15; const month = 8; const year = 2025; const MidNightAndLastThird = true; // optional calculation for midnight and last third of the night const result = getPrayerTimeByCity(countryName, cityName, day, month, year, MidNightAndLastThird); if (result.status) { console.log('Prayer times for:', result.city, result.country); console.log(result.times); } else { console.error('Error:', result.error); } ``` <details> <summary>result</summary> ```json { "status": true, "day": 15, "month": 8, "date": "8-15", "times": { "month": 8, "day": 15, "fajr": "03:51", "sunrise": "05:30", "dhuhr": "12:19", "asr": "15:58", "maghrib": "18:58", "isha": "20:13" }, "city": "Erbil", "country": "Iraq", "code": "IQ" } ``` </details> ### Get Prayer Times by Astronomical Calculation 📐 ```js const { PrayerTimes } = require('prayer-first'); const latitude = 24.7136; // geographical latitude of the location in decimal Ex: Erbil latitude const longitude = 46.6753; // geographical longitude of the location in decimal Ex: Erbil longitude const timeZone = 3; // local time zone offset from UTC Example: UTC+3 const methodParams = [18, 1, 0, 0, 17]; // Optional methodParams: by defult is useing MWL - Muslim World League method const asrMethod = 1; // 1 for Shafi'i, 2 for Hanafi - Optional asrMethod: by defult is Shafi const highLatitudeRule = 'NONE'; // 'MID_NIGHT', 'ONE_SEVEN', 'ANGLE_BASED' - Optional defult is 'NONE' const today = new Date(); const calculator = new PrayerTimes(latitude, longitude, timeZone, methodParams, asrMethod, highLatitudeRule); const result = calculator.getPrayerTimes(today); console.log("Astronomical Prayer Times:"); console.log(result.times); ``` <details> <summary>result</summary> ```json { "status": true, "city": "Based on Astronomical Calculation", "day": 4, "month": 8, "times": { "fajr": "04:00", "sunrise": "05:23", "dhuhr": "11:59", "asr": "15:26", "maghrib": "18:36", "isha": "19:54" } } ``` </details> ### Flexible Day Parameter 📆 Works With getPrayerTimeByCity & getPrayerTime Function ```js const { getPrayerTimeByCity } = require('prayer-first'); // Get prayer times for full month Ex: August const fullMonth = getPrayerTimeByCity('IQ', 'Erbil', 8); // Get prayer times for full year 2025 const fullYear = getPrayerTimeByCity('IQ', 'Erbil', 2025); // Get prayer times for specific day const oneDay = getPrayerTimeByCity('IQ', 'Erbil', 15, 8, 2025); ``` <details> <summary>fullMonth</summary> ```json { "status": true, "month": 8, "times": [ { "month": 8, "day": 1, "fajr": "03:41", "sunrise": "05:19", "dhuhr": "12:20", "asr": "16:05", "maghrib": "19:13", "isha": "20:28" }, { "month": 8, "day": 2, "fajr": "03:41", "sunrise": "05:20", "dhuhr": "12:20", "asr": "16:05", "maghrib": "19:12", "isha": "20:27" }, ... ], "city": "Erbil", "country": "Iraq", "code": "IQ" } ``` </details> <details> <summary>fullYear</summary> ```json { "status": true, "times": [ { "month": 1, "day": 1, "fajr": "06:02", "sunrise": "07:21", "dhuhr": "12:16", "asr": "14:45", "maghrib": "17:06", "isha": "18:21" }, { "month": 1, "day": 2, "fajr": "06:03", "sunrise": "07:21", "dhuhr": "12:16", "asr": "14:45", "maghrib": "17:06", "isha": "18:21" }, ... ], "city": "Erbil", "country": "Iraq", "code": "IQ" } ``` </details> <details> <summary>specific day</summary> ```json { "status": true, "day": 15, "month": 8, "date": "8-15", "times": { "month": 8, "day": 15, "fajr": "03:51", "sunrise": "05:30", "dhuhr": "12:19", "asr": "15:58", "maghrib": "18:58", "isha": "20:13" }, "city": "Erbil", "country": "Iraq", "code": "IQ" } ``` </details> See examples in the [`examples`](./examples) folder. ## LICENSE This project is licensed under the **GNU General Public License v3.0**. It also utilizes data from the **Muslim DB project** by Kosrat D. Ahmad originally licensed under the **Apache License 2.0**. We acknowledge and appreciate the foundational work provided by the original author All modifications, enhancements, or additional functionality introduced in this project have been independently developed by **Atta** and are **not affiliated with or endorsed by the original Muslim DB project or its creator**. - [GPLv3 License](https://www.gnu.org/licenses/gpl-3.0.txt) - [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0)