Prayer Times

Fetch prayer times by city, address, or coordinates

Overview

The prayer times API provides functions to fetch prayer times from the Aladhan API. All functions return prayer data including:

• All daily prayer times (Fajr, Sunrise, Dhuhr, Asr, Maghrib, Isha)
• Gregorian and Hijri date information
• Calculation method and school metadata
• Timezone and coordinate information

Fetch by City

fetchTimingsByCity

Fetch prayer times for a specific city and country.

import { fetchTimingsByCity } from 'ramadan-cli';

const data = await fetchTimingsByCity({
  city: 'Lahore',
  country: 'Pakistan',
  method: 1,  // Optional: Karachi method
  school: 1,  // Optional: Hanafi school
  date: new Date('2024-03-15'), // Optional: specific date
});

console.log(data.timings.Fajr);    // "05:30"
console.log(data.timings.Maghrib); // "18:45"

options · FetchByCityOptions · required

Configuration object for fetching prayer times

Show properties

city · string · required

City name (e.g., “Lahore”, “Istanbul”)

country · string · required

Country name (e.g., “Pakistan”, “Turkey”)

method · number

Calculation method ID (0-23). See calculation methods

school · number

Asr calculation school: 0 for Shafi (standard) or 1 for Hanafi (later Asr)

date · Date

Target date for prayer times. Defaults to current date

return · Promise<PrayerData>

Returns a promise that resolves to prayer data

Fetch by Address

fetchTimingsByAddress

Fetch prayer times using a free-form address string. The API will geocode the address.

import { fetchTimingsByAddress } from 'ramadan-cli';

const data = await fetchTimingsByAddress({
  address: 'San Francisco, CA, USA',
  method: 2,  // ISNA method for North America
  school: 0,  // Shafi school
});

options · FetchByAddressOptions · required

Show properties

address · string · required

Free-form address string (e.g., “New York, USA”, “123 Main St, London”)

method · number

Calculation method ID (0-23)

school · number

Asr calculation school (0 or 1)

date · Date

Target date. Defaults to current date

return · Promise<PrayerData>

Prayer data for the specified address

Fetch by Coordinates

fetchTimingsByCoords

Fetch prayer times using latitude and longitude coordinates.

import { fetchTimingsByCoords } from 'ramadan-cli';

const data = await fetchTimingsByCoords({
  latitude: 31.5204,
  longitude: 74.3587,
  method: 1,
  school: 1,
  timezone: 'Asia/Karachi', // Optional but recommended
});

options · FetchByCoordsOptions · required

Show properties

latitude · number · required

Latitude coordinate (-90 to 90)

longitude · number · required

Longitude coordinate (-180 to 180)

method · number

Calculation method ID

school · number

Asr calculation school

timezone · string

IANA timezone string (e.g., “Asia/Karachi”, “America/New_York”). Recommended for accurate times

date · Date

Target date. Defaults to current date

return · Promise<PrayerData>

Prayer data for the coordinates

Next Prayer

fetchNextPrayer

Fetch the next upcoming prayer time for today.

import { fetchNextPrayer } from 'ramadan-cli';

const data = await fetchNextPrayer({
  latitude: 31.5204,
  longitude: 74.3587,
  method: 1,
  timezone: 'Asia/Karachi',
});

console.log(data.nextPrayer);     // "Asr"
console.log(data.nextPrayerTime); // "16:30"

options · FetchNextPrayerOptions · required

Show properties

latitude · number · required

Latitude coordinate

longitude · number · required

Longitude coordinate

method · number

Calculation method ID

school · number

Asr calculation school

timezone · string

IANA timezone string

return · Promise<NextPrayerData>

Prayer data with next prayer information

Ramadan Calendar

fetchCalendarByCity

Fetch the entire Ramadan prayer calendar for a city.

import { fetchCalendarByCity } from 'ramadan-cli';

// Fetch Ramadan 1446 (full month)
const calendar = await fetchCalendarByCity({
  city: 'Istanbul',
  country: 'Turkey',
  year: 1446,  // Hijri year
  month: 9,    // Optional: month number (9 = Ramadan)
  method: 13,  // Turkey method
});

console.log(calendar.length); // 30 days
console.log(calendar[0].timings.Fajr); // First day Fajr time

options · FetchCalendarByCityOptions · required

Show properties

city · string · required

City name

country · string · required

Country name

year · number · required

Gregorian year

month · number

Gregorian month (1-12). If omitted, returns entire year

method · number

Calculation method ID

school · number

Asr calculation school

return · Promise<ReadonlyArray<PrayerData>>

Array of prayer data for each day

fetchCalendarByAddress

Fetch prayer calendar using an address string.

import { fetchCalendarByAddress } from 'ramadan-cli';

const calendar = await fetchCalendarByAddress({
  address: 'London, UK',
  year: 2024,
  month: 3,  // March
  method: 3, // MWL method
});

options · FetchCalendarByAddressOptions · required

Same as FetchCalendarByCityOptions but with address instead of city/country

fetchHijriCalendarByCity

Fetch Ramadan calendar using Hijri calendar date.

import { fetchHijriCalendarByCity } from 'ramadan-cli';

// Fetch Ramadan 1446
const ramadan = await fetchHijriCalendarByCity({
  city: 'Mecca',
  country: 'Saudi Arabia',
  year: 1446,  // Hijri year
  month: 9,    // Ramadan (required for Hijri calendar)
  method: 4,   // Umm al-Qura method
});

options · FetchHijriCalendarByCityOptions · required

Show properties

city · string · required

City name

country · string · required

Country name

year · number · required

Hijri year

month · number · required

Hijri month (1-12, 9 = Ramadan)

method · number

Calculation method ID

school · number

Asr calculation school

fetchHijriCalendarByAddress

Fetch Hijri calendar using an address.

import { fetchHijriCalendarByAddress } from 'ramadan-cli';

const ramadan = await fetchHijriCalendarByAddress({
  address: 'Dubai, UAE',
  year: 1446,
  month: 9,
  method: 16,
});

Calculation Methods

fetchMethods

Get all available prayer time calculation methods.

import { fetchMethods } from 'ramadan-cli';

const methods = await fetchMethods();

// Access specific method
console.log(methods['2']);
// {
//   id: 2,
//   name: "Islamic Society of North America (ISNA)",
//   params: { Fajr: 15, Isha: 15 }
// }

return · Promise<MethodsResponse>

Record mapping method IDs to calculation method details

Common Calculation Methods

North America

const data = await fetchTimingsByCity({
  city: 'New York',
  country: 'USA',
  method: 2, // ISNA
});

Qibla Direction

fetchQibla

Get the Qibla direction (bearing to Mecca) for any location.

import { fetchQibla } from 'ramadan-cli';

const qibla = await fetchQibla(31.5204, 74.3587);

console.log(qibla.direction); // 255.88 (degrees from North)
console.log(qibla.latitude);  // Input latitude
console.log(qibla.longitude); // Input longitude

latitude · number · required

Latitude coordinate

longitude · number · required

Longitude coordinate

return · Promise<QiblaData>

Qibla direction data

Show properties

latitude · number

Input latitude

longitude · number

Input longitude

direction · number

Qibla bearing in degrees from North (0-360)

Method IDs Reference

ID	Method Name	Region
0	Jafari (Shia Ithna-Ashari)	Shia communities
1	University of Islamic Sciences, Karachi	Pakistan, Bangladesh, India
2	Islamic Society of North America (ISNA)	North America
3	Muslim World League (MWL)	Europe, worldwide
4	Umm al-Qura University, Makkah	Saudi Arabia
5	Egyptian General Authority of Survey	Egypt, Middle East
7	Institute of Geophysics, University of Tehran	Iran
8	Gulf Region	Gulf states
9	Kuwait	Kuwait
10	Qatar	Qatar
11	Majlis Ugama Islam Singapura	Singapore
12	Union Organization Islamic de France	France
13	Diyanet İşleri Başkanlığı	Turkey
14	Spiritual Administration of Muslims of Russia	Russia
15	Moonsighting Committee Worldwide	Various
16	Dubai	UAE
17	Jabatan Kemajuan Islam Malaysia (JAKIM)	Malaysia, Brunei
18	Tunisia	Tunisia
19	Algeria	Algeria
20	KEMENAG - Indonesia	Indonesia
21	Morocco	Morocco
22	Comunidade Islamica de Lisboa	Portugal
23	Jordan	Jordan

Example: Full Integration

import {
  fetchTimingsByCity,
  fetchCalendarByCity,
  fetchQibla,
  guessLocation,
  type PrayerData,
} from 'ramadan-cli';

// Auto-detect location
const location = await guessLocation();

if (location) {
  // Get today's prayer times
  const todayPrayers = await fetchTimingsByCity({
    city: location.city,
    country: location.country,
    method: 2,
  });
  
  console.log('Fajr:', todayPrayers.timings.Fajr);
  console.log('Maghrib:', todayPrayers.timings.Maghrib);
  
  // Get Ramadan calendar
  const ramadan = await fetchCalendarByCity({
    city: location.city,
    country: location.country,
    year: 2024,
    month: 3,
    method: 2,
  });
  
  console.log(`Ramadan has ${ramadan.length} days`);
  
  // Get Qibla direction
  const qibla = await fetchQibla(location.latitude, location.longitude);
  console.log(`Qibla: ${qibla.direction}°`);
}