بِسْمِ اللهِ الرَّحْمٰنِ الرَّحِيْمِ
The AlAdhan App and API both now support the following calculation methods:
- Muslim World League
- Islamic Society of North America
- Egyptian General Authority of Survey
- Umm Al-Qura University, Makkah
- University of Islamic Sciences, Karachi
- Institute of Geophysics, University of Tehran
- Shia Ithna-Ashari, Leva Institute, Qum
- Gulf Region
- Majlis Ugama Islam Singapura, Singapore
- Union Organization islamic de France
- Diyanet İşleri Başkanlığı, Turkey
- Spiritual Administration of Muslims of Russia
- Moonsighting Committee
- Dubai, UAE - this is not an official calculation but based on the research done by the Batoul Apps team which uses 18.2 degrees for both Fajr and Isha
If you understand how these work and want to see some detail, just see https://api.aladhan.com/methods.
Have some kind of JSON formatter plugin installed on your browser to view this.
What really is a Method?
The mathematical side of how the calculation should work is generally agreed upon in the Islamic world.
Then again, this is an assumption I am making based on the number of countries that use the angle based calculation
(and please note that I am not religiously or formally qualified and am providing
this information with absolute humility in the hope that it may be useful).
However, based on location, government preferences, and other 'factors', there are
differences in the methods that produce, sometimes, a substantial variation in timings. If the mathematical side
interests you, have a look at this excellent explanation: http://praytimes.org/wiki/Prayer_Times_Calculation.
A calculation method is typically made up of the following:
- The Fajr Angle
- The Maghrib Angle or minutes after sunset that Maghrib should be
- The Isha Angle or minutes after Maghrib that Isha should be
The AlAdhan API has default values for all 3, and most methods only specifically specify Fajr and Isha.
Most countries adhere to one of the above methods, and they then tune the timings further, by adding
a few minutes here and there, based on criteria that may seem completely arbitrary. So, even if you use
the Gulf Region method and compare the timings to Dubai's IACAD or the UAE's Awqaf, you will see a couple
of minutes differing. Usually this difference can be anywhere from 1 to 5 minutes.
How to Use the Methods
You should probably use the method associated with the issuing authority closest to where you are based. This
is because they have probably computed the angles, etc. based on their location and convention.
However, at all times, you should really be using common sense to do what makes most sense and feels right.
After all, you have to offer the prayers, not the authority that came up with the method.
How to Tune and Tweak Method Timings via the API
Let's walk through an example of tuning the timings. We'll go with the GULF REGION method.
Here are its parameters:
- Method ID: 8
- Fajr Angle: 19.5 degrees
- Isha Time: 90 mins after Maghrib
Using this method, if we compute timings for the 9th of March, 2015 (https://api.aladhan.com/timingsByAddress/09-03-2015?address=Dubai,UAE&method=8), we get:
We can further tune the timings by adding the tune parameter, which accepts comma separated values (denoting addition / substraction in minutes) in the following order:
So, if we now call
our result is:
Please NOTE that tuning one prayer will not change another. So adding 3 mins to Maghrib will NOT automatically add 3 to Isha.
Customizing to create your own Method via the API
If you're not happy with the angle defintions of any of the other methods, you can use the API to create your own.
To do this, you can use any timings related endpoint, like timings, timingsByAddress, timingsByCity, calendar, calendarByAddress, etc.
For the method, pass 99 - this means you'll be passing your own method parameters in the 'methodSettings' parameter.
The methodSettings parameter accepts comma separated values in the following order:
Specify null for anyting you don't want to specify, or leave it empty. So, a custom method calculation with Fajr at 18.5 degrees and Isha at 17.5 degrees would look like:
You can further tune your custom method with the tune parameter, as above. Here's an example: