Mihrab Methods

Using mihrab-methods

As a package

npm install mihrab-methods

One entry point per authority, so an app ships only the data it needs — an Indonesian app does not carry Diyanet’s worldwide points:

Import Loads
mihrab-methods all of them
mihrab-methods/sweden, /diyanet, /morocco, /algeria, /indonesia, /turkiyetakvimi, /kazakhstan, /egypt, /brunei, /qatar, /kuwait, /jordan, /tatarstan, /cdum, /albania, /bulgaria, /banuri, /uae, /tehran, /wifaq, /tunisia one authority: its places, list and certification
mihrab-methods/locate countryAt, defaultAuthorityFor — the country at a point, and the authority whose table it prays by (the country outlines, kept apart because most apps already know their country)
mihrab-methods/standard standardTimes — a calculated day by a named convention for a point no authority here publishes for; status: 'calculated', never certified
mihrab-methods/core the calls and types with no data (load authorities yourself)

CommonJS and ES modules, with types. Node 18+, or any bundler; nothing is read from disk or fetched unless you call fetchLatestCorrections.

import { placesOf, placeById, nearestPlace, timesFor, timesForRange, candidateTimes, methodInfo } from 'mihrab-methods';
import { defaultAuthorityFor } from 'mihrab-methods/locate';

defaultAuthorityFor(59.33, 18.07);            // 'sweden' (null where none of them publishes for the point)
const { place, distanceKm } = nearestPlace('sweden', 59.33, 18.07)!;
place.id;                                     // 'sweden:stockholm' — stable; place.country 'SE'
placeById('diyanet:9146');                    // Adana

timesFor(place, '2026-10-15');                // or { year: 2026, month: 10, day: 15 } — January is 1
// {
//   status: 'certified',                     'method-only' outside the certified dates: the method alone,
//                                            on the printed minute all but rarely, never a minute further
//   date: '2026-10-15', certifiedFrom: '2024-01-01', certifiedUntil: '2027-12-31', revision: 1,
//   clock: { zone: 'Europe/Stockholm', offsetMinutes: 120, label: 'Europe/Stockholm' },
//   asrShadow: 1,                            which Asr this is: 1 one shadow length (Shafi'i), 2 two (Hanafi)
//   times: { fajr: { instant: Date, printed: '05:09', basis: 'table' }, sunrise: …, dhuhr: …, asr: …, maghrib: …, isha: … }
// }
timesFor(place, '2031-01-01', { strict: true });   // throws UncertifiedMethodError instead
timesFor(place, '2026-10-15', { asr: 'hanafi' });  // an Asr by name: 'shafii' or 'hanafi' (default 'printed', the timetable's own)
timesForRange(place, '2026-10-01', '2026-10-31');  // a month, one DayTimes per day
candidateTimes(place, '2026-10-15', { corrections: false }); // the formula alone — research
methodInfo('morocco');                        // angles, margins, rounding, revision, certification, sources, spec

basis says what each time stands on: table (inside the certified dates, and the method gave the timetable’s minute unaided), corrected (the correction list moved it a minute onto the timetable’s minute), method (the method alone: the date is outside the certified dates) or unchecked (the method alone, and no column was checked for it: the Asr the timetable does not print, and a time it does not print at all — Iran’s Asr and Isha, Tunisia’s sunrise). The Asr is the one the authority’s timetable prints unless another is asked for by name; for Tatarstan’s, the Central Muftiate’s, Jamia Banuri’s and Wifaqul Ulama’s that is the Hanafi one, and asrShadow on the answer always says which came back. The older { asrShadow: 2 } still asks for the Hanafi Asr.

printed is the wall-clock minute on clock, which is the clock the authority prints the day in: the place’s zone as kept at noon, or the table’s own clock where it keeps one no zone does (Morocco’s GMT+1 until September 2026; some of Diyanet’s). An app shows printed and schedules on instant; nothing needs rounding or converting.

Where no authority answers: mihrab-methods/standard

For a point none of these authorities publishes for, an app that must show something can ask for a calculated day — the plain astronomical calculation by a well-known convention, not an authority’s method, and held to nobody’s timetable:

import { standardTimes } from 'mihrab-methods/standard';

standardTimes({ lat: 48.86, lon: 2.35, date: '2026-10-15', tz: 'Europe/Paris' });
// { status: 'calculated', convention: 'mwl', clock, asrShadow: 1, times: { fajr: { instant, printed }, … } }

tz is required: the library has no map of the world’s zones, so the IANA zone the times are printed in is the caller’s to give. convention is mwl (the default), isna, egypt, karachi or ummalqura (STANDARD_CONVENTIONS has their angles); asr: 'hanafi' gives two shadow lengths. The answer’s status is always calculated, so it cannot be mistaken for a certified day. There are no margins and no high-latitude rule: where a twilight does not form the day’s times is null.

As an HTTP API

https://mihrab-api.elghamri.se

The public API serves main’s methods and lists, deployed with every change (api/worker.ts, Cloudflare Workers): JSON over GET, no key, CORS open, nothing logged or stored, answers cached for an hour.

Using it. It is free to call, from a site, a script or a prototype, and it is run without a promise of availability and may be rate-limited if one caller crowds out the rest. An app or a mosque screen that people rely on should carry the library instead (npm or PyPI: the same times, offline, no request per reader), or run the handler itself:

npm run serve      # http://localhost:8787
GET /v1/times?lat=30.04&lng=31.24&date=2026-10-15
GET /v1/times?authority=diyanet&lat=41.01&lng=28.98&date=2026-10-15
GET /v1/times?place=algeria:27&from=2026-10-01&to=2026-10-31
GET /v1/nearest?authority=morocco&lat=33.57&lng=-7.59
GET /v1/authority?lat=59.33&lng=18.07
GET /v1/places?authority=indonesia
GET /v1/methods
GET /openapi.json

A point with no authority is answered by the authority it belongs to (defaultAuthorityFor: the country’s own, or the body that lists a town there), from that authority’s nearest place. The answer names the place, says how far it is (distanceKm: the times are that place’s, not the point’s own; maxKm= refuses beyond a distance) and how the authority was chosen (authorityFrom: location or request). Where no authority here publishes for the point the answer is 404, not another country’s method: name one with authority= to ask for it anyway. Or add fallback=standard&tz=<IANA zone> (and optionally convention=): such a point is then answered with the calculated day above — status: calculated, fallback: standard, place: null — instead of 404. A point an authority does publish for is answered by its method as always.

GET / lists the routes and each method’s revision and certification, and /openapi.json describes them (OpenAPI 3.1, written from the same table the handler dispatches on: src/openapi.ts, npm run openapi). The handler is src/server.ts; tools/serve.ts serves it on Node, api/worker.ts at the edge.

In another language

docs/methods.md states each method in prose and formulas, and test/vectors.json is a small sample of places, dates and the times to expect — enough to prove a port matches, too small to be a timetable.

ports/ has the methods in Python, Swift, Kotlin and Dart, each with no dependencies and each held to that sample on every push.

This repository

npm install           # NODE_ENV must not be "production", or the dev tools are skipped
npm test              # the library, the schemas, the vectors; the table checks when the tables are present
npm run build         # dist/ (CommonJS and ESM, with types)
npm run verify        # every method against the reference timetables
npm run verify -- morocco indonesia
npm run verify -- --alone   # each method without its correction list
npm run corrections   # rewrites Sweden's correction list (`-- diyanet`, `-- morocco`, … for the others)
npm run certify       # rewrites certification.json — what may be used
npm run certify -- morocco   # just those methods; the others keep their entries
npm run vectors       # rewrites test/vectors.json (after a method revision)
npm run port-sample -- <file>   # a wide sample in the same shape, for checking a port; not kept

The reference timetables are not part of this repository; point MIHRAB_TABLES at them (default .tables). Without them candidateTimes still runs, the checks and their tests skip, and npm run certify writes nothing.

Layout

Path What
src/methods/ The methods: Sweden and Diyanet (sweden.ts), Morocco, Algeria, Indonesia, Türkiye Takvimi, Kazakhstan, Egypt, Brunei, Qatar, Kuwait, Jordan, Tatarstan, Russia’s Central Muftiate, Albania, Bulgaria, Pakistan’s Jamia Banuri Town, the United Arab Emirates, Iran’s Institute of Geophysics, the United Kingdom’s Wifaqul Ulama, Tunisia’s Institut National de la Météorologie; their revisions
src/sun/preciseSun.ts VSOP87 apparent sun, after Astronomy Engine: within about 0.05 s and 0.5″ of JPL’s DE421
src/core/ The calls (api.ts), the computation they share (compute.ts), dates, clocks, the correction-list index, fetchLatestCorrections
src/authorities/ Each authority’s places, at the point (and Morocco’s horizon) its method is computed at, with its description
src/index.ts, src/<authority>.ts, src/locate.ts, src/standard.ts, src/core.ts The package’s entry points
data/places/, data/corrections/, data/locate/ The place lists and fitted points, the correction lists, the country outlines — embedded into the code by scripts/embed.mjs at build time
certification.json, schemas/ The 100 % gate’s record, and the schemas of the files apps read
tools/verify.ts, tools/certify.ts, tools/corrections.ts The day-by-day check against the timetables; the certification; the correction lists
tools/vectors.ts, test/vectors.json, docs/methods.md For ports: the sample and the written method
ports/ The methods in Python, Swift, Kotlin and Dart, and each one’s check against the sample
src/server.ts, src/openapi.ts The HTTP API: the handler, and the routes with their description (docs/openapi.json)
tools/serve.ts, api/worker.ts The API on Node, and at the edge
scripts/outlines.py Adds a country, or a neighbour’s border strip, to data/locate/countryOutlines.json
scripts/release-check.mjs Whether npm needs a release, and which
scripts/stats.mjs The usage counts (npm, the API) in the README, weekly

Back into Mihrab

A method that improves here goes back as the same file in Mihrab’s src/providers/ (and its points file in src/providers/data/). The app reads certification.json and the lists from this repository’s main; that feed does not change shape between versions (schemas/).

Edit this page on GitHub · Report a problem