How Global Prayer Times Calculates What It Shows

01 · Scope

What this document represents

This public guide explains the user-facing calculations and Islamic information shown by the global Telegram bot. It covers prayer times, high-latitude adjustments, Qibla direction, Hijri dates, Islamic occasions, and the rolling calendar—not deployment or infrastructure.

It is a transparent calculation guide, not a religious ruling. Local mosques and recognized authorities may publish schedules with different conventions, observation decisions, safety margins, or moon-sighting decisions.

Prayer times are calculated locally.

Google Maps is consulted only when a user sets a location, to resolve an IANA timezone, ISO country code, city label, and place identifier. Google does not provide the prayer schedule.

02 · Pipeline

From a Telegram location to a schedule

1
Validate coordinates
Latitude must be within −90°…90° and longitude within −180°…180°.
2
Resolve local civil time
The bot obtains the IANA timezone and ISO country code, then stores coordinates rounded to three decimals.
3
Select a default
The country chooses an initial twilight method. The user can replace it at any time.
4
Calculate solar events
The requested instant is converted to the local timezone, and the bot calculates/caches the entire local year.
5
Adapt and finalize
It applies the high-latitude rule when necessary, per-prayer minute corrections, and nearest-minute rounding.
6
Calculate Hijri information
The local Gregorian date is converted separately. Hijri correction changes the displayed date and occasion matching, but never moves prayer times.

\[ \phi_s=\frac{\operatorname{round}(1000\phi)}{1000},\qquad \lambda_s=\frac{\operatorname{round}(1000\lambda)}{1000} \]

Stored location precision is approximately a city block; raw Telegram precision is not retained.

03 · Solar geometry

Finding the Sun’s event times

The underlying engine implements NREL SPA to obtain topocentric solar position. The prayer library searches around solar transit for the moment the Sun reaches the required elevation.

For intuition, with latitude \(\phi\), solar declination \(\delta\), local hour angle \(H\), and solar elevation \(h\):

\[ \sin h=\sin\phi\sin\delta+\cos\phi\cos\delta\cos H \] \[ H_0=\arccos\!\left(\frac{\sin h_0-\sin\phi\sin\delta}{\cos\phi\cos\delta}\right) \]

The morning solution occurs before transit; the evening solution occurs after it. If the arccos argument is outside \([-1,1]\), the target elevation is not reached that day. That is the geometric reason a high-latitude fallback may be required.

Fajr

Sun reaches the method’s negative Fajr angle before transit.

Sunrise

SPA sunrise at sea-level elevation settings.

Dhuhr

Solar transit; no built-in delay.

Asr

Post-transit shadow-ratio elevation.

Maghrib

SPA sunset.

Isha

Negative Isha angle, or +90 minutes for Umm al-Qura.

04 · Twilight conventions

All calculation methods available in the bot

The method changes Fajr and Isha only. Sunrise, Dhuhr, Asr, and Maghrib keep the definitions above.

Method	Fajr	Isha	Automatic default
Muslim World League	18°	17°	All other countries
Egyptian General Authority	19.5°	17.5°	Egypt
Umm al-Qura	18.5°	Maghrib + 90 min	Saudi Arabia
Karachi	18°	18°	Pakistan, India, Bangladesh, Afghanistan
ISNA	15°	15°	United States, Canada
Diyanet	18°	17°	Turkey
Kemenag	20°	18°	Indonesia
MUIS	20°	18°	Singapore
JAKIM	20°	18°	Malaysia

\[ h(t_F)=-\theta_F,\;t_F<t_{transit},\qquad h(t_I)=-\theta_I,\;t_I>t_{transit} \]

For Umm al-Qura, final Isha is \(t_I=t_M+90\text{ minutes}\). This fixed rule is applied after the general high-latitude adapter, so the selected high-latitude rule can affect Umm al-Qura Fajr but does not replace its fixed Isha duration.

05 · Asr

The selected madhab changes the shadow factor

Let \(k=1\) for Shafi’i, Maliki, and Hanbali timing, and \(k=2\) for Hanafi timing. The target solar elevation is:

\[ h_A=\operatorname{arccot}\!\left(k+\tan|\delta-\phi|\right), \qquad \operatorname{arccot}(x)=\arctan(1/x) \]

The engine finds this target after transit. The Hanafi factor normally produces a later Asr because the target Sun elevation is lower.

06 · High latitude

When normal twilight is unavailable

A day is marked abnormal if sunrise or sunset is missing, or if astronomical dawn/dusk at −18° is missing. The configured adapter changes a date only when Fajr or Isha is missing and both sunrise and Maghrib still exist.

\[ D=t_M-t_R,\qquad N=24\text{ hours}-D \] \[ t_F=t_R-p_FN,\qquad t_I=t_M+p_IN \]

Angle based\(p_F=\theta_F/60\)\(p_I=\theta_I/60\)

The method angles determine the fractions of night.

Middle night\(p_F=1/2\)\(p_I=1/2\)

Both events are placed at the middle-night boundary.

One seventh\(p_F=1/7\)\(p_I=1/7\)

The first and last seventh of the night are used.

Extreme-latitude limitation

All three exposed rules require sunrise and sunset. During polar day or polar night they cannot synthesize a complete schedule. Users should follow an appropriate local authority in that situation.

07 · Finalization

User corrections, rounding, and caching

Each prayer can have a whole-minute correction \(\Delta_p\) from −30 to +30. The result is corrected and then rounded to the nearest minute:

\[ t_{p,shown}=\operatorname{round}_{minute}(t_{p,base}+\Delta_p) \]

A correction changes only that prayer. Year schedules are cached by rounded coordinates, timezone, method, madhab, high-latitude rule, all six corrections, and year. Caching changes performance, never the result.

08 · Direction

How the Qibla bearing is calculated

The Qibla tool uses the saved rounded coordinates and the Kaaba coordinates \(21.4225^\circ\text{ N}, 39.8262^\circ\text{ E}\). It calculates the initial great-circle bearing: the direction in which the shortest path over the Earth's surface begins.

Let the user location be \((\phi,\lambda)\), the Kaaba be \((\phi_K,\lambda_K)\), and \(\Delta\lambda=\lambda_K-\lambda\). In radians:

\[ \beta=\operatorname{atan2}\!\left( \sin\Delta\lambda\cos\phi_K,\, \cos\phi\sin\phi_K-\sin\phi\cos\phi_K\cos\Delta\lambda \right) \] \[ B=\left(\frac{180\beta}{\pi}+360\right)\bmod 360 \]

\(B\) is clockwise from geographic north: north \(0^\circ\), east \(90^\circ\), south \(180^\circ\), west \(270^\circ\).

The displayed surface distance uses the haversine formula with mean Earth radius \(R=6371.0088\text{ km}\):

\[ a=\sin^2\!\frac{\phi_K-\phi}{2}+ \cos\phi\cos\phi_K\sin^2\!\frac{\Delta\lambda}{2}, \qquad d=2R\arcsin\sqrt{a} \]

Compass readings are device-dependent.

The numeric result is a geographic great-circle bearing. The optional live arrow uses the phone's absolute orientation sensor, which can be affected by calibration, nearby metal, magnetic interference, and the difference between magnetic and geographic north.

09 · Hijri calendar

Gregorian to Hijri, and back

The bot converts the requested instant to the saved timezone and takes its local Gregorian date \(G\). A user correction \(a\in\{-2,-1,0,1,2\}\) is applied before Hijri conversion: \(G'=G+a\) civil days.

Prayer times remain attached to \(G\). The correction changes the displayed Hijri label and the Gregorian day on which a Hijri occasion matches.

1. Convert Gregorian date to Julian day

January and February are treated as months 13 and 14 of the previous year. For adjusted \(Y',M'\), day \(d\), fraction \(f\), and Gregorian correction \(B\):

\[ A=\left\lfloor\frac{Y'}{100}\right\rfloor,\qquad B=2+\left\lfloor\frac{A}{4}\right\rfloor-A \] \[ JD=1720994.5+\lfloor365.25Y'\rfloor+\lfloor30.6001(M'+1)\rfloor+B+d+f \]

2. Preferred Umm al-Qura lookup

The bundled lunation table covers 14 March 1937 through 16 November 2077. At UTC noon, the converter computes \(CJDN=\lfloor JD\rfloor\) and \(MCJDN=CJDN-2400000\). If \(L_i\) is the first table entry greater than MCJDN:

\[ ILN=i+16260,\qquad y=\left\lfloor\frac{ILN-1}{12}\right\rfloor+1 \] \[ m=ILN-12\left\lfloor\frac{ILN-1}{12}\right\rfloor,\qquad d=MCJDN-L_{i-1}+1 \]

The inverse supported by the library is \(ILN=m+12(y-1)\), \(i=ILN-16260\), \(MCJDN=d-1+L_{i-1}\), and \(JD=MCJDN+2400000-0.5\). The bot currently uses Gregorian → Hijri for display; it does not expose the reverse conversion in the UI.

3. Arithmetic fallback

Outside the table, the bot uses the deterministic 30-year tabular cycle. It contains 10,631 days; leap years are 2, 5, 7, 10, 13, 16, 18, 21, 24, 26, and 29. Months alternate 30/29 days, and month 12 has 30 days in a leap year.

\[ JD_H=1948438.5+354(y-1)+\left\lfloor\frac{3+11y}{30}\right\rfloor+ 29(m-1)+\left\lfloor\frac{m}{2}\right\rfloor+d \]

This fallback and Umm al-Qura are calculated calendars. Local crescent observation can differ, which is why the bot allows a ±2-day Hijri correction for both the label and occasion matching.

10 · Islamic dates

How Islamic occasions are selected

The bot does not keep a separate list of Gregorian dates. It calculates the corrected Hijri date for each local Gregorian day and compares its Hijri month and day with a curated catalog. Therefore location timezone and the user's Hijri correction determine which local Gregorian day displays an occasion.

Hijri date	Category	Occasion	Reference or qualification
10 Muharram	Fasting	Ashura	Sahih Muslim 1162a
12 Rabi al-Awwal	Commonly observed	Mawlid al-Nabi	Exact historical date and observance differ; Quran 33:56, Sahih Muslim 1162e
27 Rajab	Commonly observed	Isra and Mi'raj	Precise date is not established; Quran 17:1
15 Sha'ban	Commonly observed	Mid-Sha'ban	Practices and scholarly assessment of specific evidence differ
1 Ramadan	Major	Beginning of Ramadan	Quran 2:185
21 Ramadan	Major	Last ten nights begin	Surah Al-Qadr, Sahih al-Bukhari 2017
1 Shawwal	Major	Eid al-Fitr	Confirm the local date; Quran 2:185
1 Dhu al-Hijjah	Major	First ten days begin	Sahih al-Bukhari 969
9 Dhu al-Hijjah	Fasting	Day of Arafah	Recommended fast for non-pilgrims; Sahih Muslim 1162a
10 Dhu al-Hijjah	Major	Eid al-Adha	Confirm the local date; Quran 22:36

Calculated date does not replace local confirmation.

Ramadan, Eid, and other lunar dates can differ with local crescent observation. “Commonly observed” is a deliberate label: those dates or practices are not presented as universally agreed. All three occasion reminder categories are opt-in.

11 · Rolling calendar

How each user's calendar is generated

The private calendar feed uses the user's saved location, timezone, calculation method, madhab, high-latitude rule, minute corrections, and Hijri correction. Every time a calendar provider fetches the URL, the bot recalculates today and the following 29 local days.

Prayer events

Timed events use each day's calculated local prayer instants.

Islamic occasions

Matching corrected Hijri dates become all-day events with guidance and sources.

Stable updates

Stable event identifiers let a provider update changed times instead of duplicating them.

The feed rolls forward when fetched; the bot does not permanently store 30 future days or run a separate calendar cron job. Google Calendar controls its own refresh schedule, so a new day or settings change may not appear immediately.

12 · Interpretation

Why another timetable may differ

Convention

Different Fajr/Isha angles or Asr factor.

Latitude policy

Different treatment when twilight disappears.

Astronomy

Elevation, refraction, or solar model choices.

Civil time

Timezone or daylight-saving assumptions.

Institution

Safety margins and local adjustments.

Calendar

Observed crescent versus calculated date.

Compass

Sensor calibration, magnetic interference, and north reference.

13 · References

Calculation references

This guide is versioned with the open-source bot so its explanation can be reviewed and corrected as the calculations evolve.