Code Manual
From Pray Times
PrayTimes is a small program providing a set of handy functions to calculate prayer times for any date and location, based on a variety of calculation methods currently used in Muslim communities.
PrayTimes is originally written in JavaScript. This manual provides information on how to use PrayTimes on a web-page or JavaScript-based widget to compute prayer times for any given time and location.
Contents |
Download and Examples
Download:
- Latest release: prayTimes.js (ver 2.0)
- License: Creative Commons Attribution 3.0 Unported
Examples:
- A simple example: simple.htm
- Monthly timetable: monthly.htm
- Yearly prayer times: yearly.htm
General Usage
The first step for using PrayTimes in a web-page or widget is to include it using a line like this:
<script type="text/javascript" src="prayTimes.js"></script>
After including prayTimes.js, an object named prayTimes is created and is ready to use. We can immediately get the prayer times (using the default settings) from this object. For example, to get today's prayer times for a location with latitude 43, longitude -80 and time zone -5, we can call:
prayTimes.getTimes(new Date(), [43, -80], -5);
There are several functions for adjusting calculation parameters. For example, we can call the following function (before calling getTimes) to change the calculation method to ISNA:
prayTimes.setMethod('ISNA');
Details of the functions available in PrayTimes along with their description are provided below.
Get Prayer Times
The following function is used to retrieve prayer times for a given date and location:
getTimes (date, coordinates, timezone, dst, format)
The input parameters are described below:
- date
- The date for which prayer times are calculated. You can use
new Date()to specify today. Date can be also entered as a triple[year, month, day]. For example,[2009, 2, 26]specifies February 26, 2009.
- coordinates
- Specifies the coordinates of the input location as a triple
[latitude, longitude, elevation]. Latitude is a real number between -90 and 90, longitude is between -180 and 180, and elevation is a positive number, specifying the height in meters with respect to the surrounding terrain. The elevation parameter is optional. Examples of valid coordinates are[-43.2, 80.6]and[12.5, -25.8, 300].
- timezone
- The difference to Greenwich time (GMT) in hours.
- dst
- Daylight Saving Time: 1 if date is in daylight saving time, 0 otherwise. If omitted,
dstis assumed to be 0.
- format
- Output time format, according to the following table:
| Format | Description | Example |
|---|---|---|
| 24h | 24-hour time format | 16:45 |
| 12h | 12-hour time format | 4:45 pm |
| 12hNS | 12-hour format with no suffix | 4:45 |
| Float | Floating point number | 16.75 |
Return Value
getTimes return an associative array containing 9 prayer times (See here for the list of times and their definition.) Each time can be accessed thorough its name. For example, if the output of getTimes function is stored in an object times, the time for sunrise can be accessed through times.sunrise.
Example
var times = prayTimes.getTimes(new Date(), [43, -80], -5);
document.write('Sunrise : '+ times.sunrise)
Set Calculation Method
There are several conventions for calculating prayer times. The default convention used in PrayTimes is Muslim World League. You can change the calculation method using the following function:
setMethod (method)
method can be any of the followings:
| Method | Description |
|---|---|
| MWL | Muslim World League |
| ISNA | Islamic Society of North America |
| Egypt | Egyptian General Authority of Survey |
| Makkah | Umm al-Qura, Makkah |
| Karachi | University of Islamic Sciences, Karachi |
| Jafari | Shia Ithna Ashari (Ja`fari) |
| Tehran | Institute of Geophysics, University of Tehran |
More information on the above calculation methods is provided here.
Example
prayTimes.setMethod('Makkah');
Adjusting Parameters
The calculating parameters can be adjusted using the following function:
adjust (parameters)
parameters is an associative array composed of any number of the following parameters:
| Parameter | Values | Description | Example |
|---|---|---|---|
| imsak | degrees | twilight angle | 18 |
| minutes | minutes before fajr | 10 min | |
| fajr | degrees | twilight angle | 15 |
| zuhr | minutes | minutes after mid-day | 1 min |
| asr | method | asr juristic method; see the table below | Standard |
| factor | shadow length factor for realizing asr | 1.7 | |
| maghrib | degrees | twilight angle | 4 |
| minutes | minutes after sunset | 15 min | |
| isha | degrees | twilight angle | 18 |
| minutes | minutes after maghrib | 90 min | |
| midnight | method | midnight method; see the table below | Standard |
| highLats | method | higher latitudes adjustment; see below | None |
- asr methods
| Method | Description (more info) |
|---|---|
| Standard | Shafii, Maliki, Jafari and Hanbali (shadow factor = 1) |
| Hanafi | Hanafi school of tought (shadow factor = 2) |
- midnight methods
| Method | Description |
|---|---|
| Standard | The middle of Sunset to Sunrise |
| Jafari | The middle of Maghrib to Fajr |
- higher latitudes methods
| Method | Description (more info) |
|---|---|
| None | No adjustments |
| NightMiddle | The middle of the night method |
| OneSeventh | The 1/7th of the night method |
| AngleBased | The adaptive angle-based method |
Example
prayTimes.adjust( {fajr: 16, zuhr: '5 min', asr: 'Hanafi', isha: 15} );
Tuning Times
You can further tune calculated prayer times (for precaution) using the following function:
tune (offsets)
offsets is an associative array containing time offsets in minutes for each prayer time.
Example
prayTimes.tune( {sunrise: -1, sunset: 3.5} );
- Note 1.
- By default, PrayTimes rounds minutes to the nearest values. To round a specific time up, you can tune it by +0.5, and to round it down, you can tune it by -0.5 minutes.
- Note 2.
- Tuning is the last step after calculating the times, and thus, has no effect on the calculation parameters. For example, if Isha is set to be 90 minutes after sunset, tuning sunset by 5 minutes will not push Isha forward.
