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/).