API Reference

The following section documents every class and function in the aladhan.py module.

Version Related Info

There are two main ways to query version information about the library.

aladhan.version_info

A named tuple that is similar to sys.version_info.

Just like sys.version_info the valid values for releaselevel are ‘alpha’, ‘beta’, ‘candidate’ and ‘final’.

aladhan.__version__

A string representation of the version. e.g. '1.0.0rc1'. This is based off of PEP 440.

Client

class aladhan.Client

Al-adhan API client.

Set to synchronous usage by default, set is_async to True if asynchronous usage wanted.

Auto handles rate limits by default, set auto_manage_rate to False if otherwise is wanted. New in v1.2.0

Example

Synchronous

import aladhan

client = aladhan.Client()
times = client.get_timings_by_address("New York")
print(times)

Asynchronous

import aladhan, asyncio

async def main():
    # --- manual closing session
    client = aladhan.Client(is_async=True)
    times = await client.get_timings_by_address("New York")
    print(times)
    await client.close()

    # --- using context
    async with aladhan.Client(is_async=True) as client:
        times = await client.get_timings_by_address("New York")
        print(times)

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

Note

For Asynchronous usage you need to initialize this class in a coroutine.

Parameters:

• is_async (bool) – Whether to be used asynchronously or not.

• auto_manage_rate (bool) – Whether to handle rate limits automatically or not.

close()

Closes the connection.

get_next_prayer_by_address(address, date=None, params=None)

Get next upcoming prayer from address.

Parameters:

• address (str) – An address string. Example: “London, United Kingdom”

• date (Optional[TimingsDateArg]) – Date for the prayer times. Default: Current date.

• params (Optional[Parameters]) – Default: Parameters()

Returns:

Prayer obj from the API response.

Return type:

Prayer

Raises:

BadRequest – Invalid parameter was passed.

New in v1.2.0

get_timings(longitude, latitude, date=None, params=None)

Get prayer times from coordinates (longitude, latitude).

Parameters:

• longitude (int or float) – Longitude coordinate of the location.

• latitude (int or float) – Latitude coordinate of the location.

• date (Optional[TimingsDateArg]) – Date for the prayer times. Default: Current date.

• params (Optional[Parameters]) – Default: Parameters()

Returns:

Timings obj from the API response.

Return type:

Timings

Raises:

BadRequest – Invalid parameter was passed.

get_timings_by_address(address, date=None, params=None)

Get prayer times from address.

Parameters:

• address (str) – An address string. Example: “London, United Kingdom”

• date (Optional[TimingsDateArg]) – Date for the prayer times. Default: Current date.

• params (Optional[Parameters]) – Default: Parameters()

Returns:

Timings obj from the API response.

Return type:

Timings

Raises:

BadRequest – Invalid parameter was passed.

get_timings_by_city(city, country, state=None, date=None, params=None)

Get prayer times from city, country and state.

Parameters:

• city (str) – The city name. Example: “London”

• country (str) – The country name or 2 character alpha ISO 3166 code. Example: “GB” or “United Kingdom”

• state (Optional[str]) – State or province. The state name or abbreviation.. Example: “Bexley”

• date (Optional[TimingsDateArg]) – Date for the prayer times. Default: Current date.

• params (Optional[Parameters]) – Default: Parameters()

Returns:

Timings obj from the API response.

Return type:

Timings

Raises:

BadRequest – Invalid parameter was passed.

get_calendar(longitude, latitude, date, params=None)

Get all prayer times for a specific calendar month/year from coordinates (longitude, latitudes).

Parameters:

• longitude (int or float) – Longitude coordinate of the location.

• latitude (int or float) – Latitude coordinate of the location.

• date (CalendarDateArg) – Date for the prayer times.

• params (Optional[Parameters]) – Default: Parameters()

Returns:

A month calendar if month parameter was given in date argument otherwise a year calendar.

Return type:

list of Timings or dict[str, list of Timings]

Raises:

BadRequest – Invalid parameter was passed.

get_calendar_by_address(address, date, params=None)

Get all prayer times for a specific calendar month/year

from address.

Parameters:

• address (str) – An address string. Example: “London, United Kingdom”

• date (CalendarDateArg) – Date for the prayer times.

• params (Optional[Parameters]) – Default: Parameters()

Returns:

A month calendar if month parameter was given in date argument otherwise a year calendar.

Return type:

list of Timings or dict[str, list of Timings]

Raises:

BadRequest – Invalid parameter was passed.

get_calendar_by_city(city, country, date, state=None, params=None)

Get all prayer times for a specific calendar month/year

from address.

Parameters:

• city (str) – The city name. Example: “London”

• country (str) – The country name or 2 character alpha ISO 3166 code. Example: “GB” or “United Kingdom”

• date (CalendarDateArg) – Date for the prayer times.

• state (Optional[str]) – State or province. The state name or abbreviation.. Example: “Bexley”

• params (Optional[Parameters]) – Default: Parameters()

Returns:

A month calendar if month parameter was given in date argument otherwise a year calendar.

Return type:

list of Timings or dict[str, list of Timings]

Raises:

BadRequest – Invalid parameter was passed.

static get_all_methods()

Gives all available prayer times calculation method.

Returns:

A dict of available calculation method from 0 to 15.

Return type:

dict[int, Method]

get_qibla(longitude, latitude)

Get the Qibla direction from a pair of coordinates.

Parameters:

• longitude (int or float) – Longitude co-ordinate.

• latitude (int or float) – Latitude co-ordinate.

Returns:

The qibla.

Return type:

Qibla

Raises:

BadRequest – Invalid parameter was passed.

New in v0.1.3

get_asma(*n)

Returns a list of asma from giving numbers.

Parameters:

n (int) – Numbers from range 1-99.

Returns:

A list of asma.

Return type:

list of Ism

Raises:

BadRequest – Invalid parameter was passed.

New in v0.1.3

get_all_asma()

Returns all 1-99 asma (allah names).

Returns:

A list of all asma.

Return type:

list of Ism

New in v0.1.3

get_hijri_from_gregorian(date=None, adjustment=0)

Convert a gregorian date to a hijri date.

Parameters:

• date (Optional[TimingsDateArg]) – Gregorian date. Default: Current date

• adjustment (Optional[int]) – Number of days to adjust. Default: 0

Returns:

Date in hijri.

Return type:

Date

Raises:

BadRequest – Invalid date or unable to convert it.

New in v1.1.0

get_gregorian_from_hijri(date, adjustment=0)

Convert a hijri date to a gregorian date.

Parameters:

• date (Optional[TimingsDateArg]) – Gregorian date. Default: Current date

• adjustment (Optional[int]) – Number of days to adjust. Default: 0

Returns:

Date in gregorian.

Return type:

Date

Raises:

BadRequest – Invalid date or unable to convert it.

New in v1.1.0

get_hijri_calendar_from_gregorian(month, year, adjustment=0)

Get a hijri calendar for a gregorian month.

Parameters:

• month (int) – Gregorian month.

• year (int) – Gregorian year.

• adjustment (Optional[int]) – Number of days to adjust. Default: 0

Returns:

Hijri Calendar.

Return type:

list of Date

New in v1.1.0

get_gregorian_calendar_from_hijri(month, year, adjustment=0)

Get a gregorian calendar for a hijri month.

Parameters:

• month (int) – Hijri month.

• year (int) – Hijri year.

• adjustment (Optional[int]) – Number of days to adjust. Default: 0

Returns:

Gregorian Calendar.

Return type:

list of Date

New in v1.1.0

get_islamic_year_from_gregorian_for_ramadan(year)

Get which islamic year for ramadan from a gregorian year.

Parameters:

year (int) – Gregorian year.

Returns:

Hijri year.

Return type:

int

Raises:

BadRequest – Unable to compute year.

get_current_time(zone)

Parameters:

zone (str) – Timezone string. ex: “Europe/London”

Returns:

The current time for the specified time zone. ex: “13:56”

Return type:

str

Raises:

BadRequest – Invalid timezone.

get_current_date(zone)

Parameters:

zone (str) – Timezone string. ex: “Europe/London”

Returns:

The current Date for the specified time zone in DD-MM-YYYY. ex: “23-02-2021”

Return type:

str

Raises:

BadRequest – Invalid timezone.

get_current_timestamp(zone)

Parameters:

zone (str) – Timezone string. ex: “Europe/London”

Returns:

The current UNIX timestamp for the specified time zone. ex: 1503495668

Return type:

int

Raises:

BadRequest – Invalid timezone.

get_current_islamic_year(adjustment=0)

Parameters:

adjustment (int) – Number of days to adjust hijri date.

Returns:

The current islamic year.

Return type:

int

Raises:

BadRequest – Unable to compute year.

get_current_islamic_month(adjustment=0)

Parameters:

adjustment (int) – Number of days to adjust hijri date.

Returns:

The current islamic month.

Return type:

int

Raises:

BadRequest – Unable to compute month.

get_next_hijri_holiday(adjustment=0)

Parameters:

adjustment (int) – Number of days to adjust hijri date.

Returns:

The Next upcoming hijri holiday.

Return type:

Date

Raises:

BadRequest – Unable to compute next holiday.

get_hijri_holidays(day, month)

Parameters:

• day (int) – Hijri day.

• month (int) – Hijri month.

Returns:

All day’s holidays, can be empty list.

Return type:

list of str

Raises:

BadRequest – Invalid day or month.

get_islamic_holidays(year, adjustment=0)

Parameters:

• year (int) – Hijri year.

• adjustment (int) – Number of days to adjust hijri date.

Returns:

All year’s holidays, 19 in total.

Return type:

list of Date

Raises:

BadRequest – Something went wrong.

get_status()

Returns:

Api’s status.

Return type:

dict

Raises:

InternalServerError – Status Check Failed.

get_special_days()

Get all islamic special days (holidays).

Returns:

A list of all special days with day,month,name keys.

Return type:

list of dict

Raises:

BadRequest – Something went wrong.

get_islamic_months()

Get all 12 islamic months.

Returns:

A dict of ‘1’ to ‘12’ as keys and dicts of number,en,ar keys.

Return type:

dict of str and dict

Raises:

BadRequest – Something went wrong.

Timings Related

Timings

class aladhan.Timings

Represents the timings that is in returned Data

Do not create this class yourself. Only get it through a getter.

data

Original fetched Data.

Type:

Data

imsak

Imsak time.

Type:

Prayer

fajr

Fajr prayer time.

Type:

Prayer

sunrise

Sunrise time.

Type:

Prayer

asr

Asr prayer time.

Type:

Prayer

maghrib

Maghrib prayer time.

Type:

Prayer

sunset

Sunset time.

Type:

Prayer

isha

Isha prayer time.

Type:

Prayer

midnight

Midnight time.

Type:

Prayer

first_third

First third time.

New in v1.2.0

Type:

Prayer

last_third

Last third time.

New in v1.2.0

Type:

Prayer

New in v0.1.4: __iter__

property as_dict

dict[str, Prayer]:

A dict of all 5 prayers and the other times

New in v0.1.4

next_prayer()

Get the next upcoming prayer. Returns None if the upcoming wasn’t in the date, so this will return None if it was from an old date.

Returns:

The upcoming prayer.

Return type:

Optional[Prayer]

Changed in v1.0.: Returns None instead of recursive calls, and no longer awaitable.

property prayers_only

dict[str, Prayer]: A dict of the 5 prayers.

Prayer

class aladhan.Prayer

Represents a Prayer obj.

Do not create this class yourself. Only get it through a getter.

data

Source data.

Type:

Data or NextPrayerData

name

Prayer name.

Type:

str

time

Prayer’s time.

Type:

datetime.datetime

time_utc

Prayer’s time in utc, might be None when time doesn’t exist because of a daylight savings switch.

Type:

Optional[datetime.datetime]

str_time

Better looking string format for prayer’s time.

Type:

str

New in v0.1.2: timings, time_utc Changed in v1.2.0: timings is removed and replaced with data.

property remaining

Optional[datetime.timedelta]:

remaining time for prayer for utc.

New in v0.1.2

NextPrayerData

class aladhan.NextPrayerData

Main class Representing the data returned from a next prayer request to API

Do not create this class yourself. Only get it through a getter.

meta

Represents the meta part.

Type:

Meta

date

Represents the date part.

Type:

Date

prayer

Represents the Prayer part.

Type:

Prayer

client

Represents the client that the Data were fetched from.

Type:

Client

New in v1.2.0

Tune

class aladhan.Tune

Represents a Tune obj that is returned from API. Can be used to make an obj that will be used as a tune param in Parameters

imsak

The tune value for imsak.

Type:

int

fajr

The tune value for fajr.

Type:

int

sunrise

The tune value for sunrise.

Type:

int

asr

The tune value for asr.

Type:

int

maghrib

The tune value for maghrib.

Type:

int

sunset

The tune value for sunset.

Type:

int

isha

The tune value for isha.

Type:

int

midnight

The tune value for midnight.

Type:

int

New in v1.0.: __iter__

classmethod from_str(s)

Makes a Tune obj from a value string.

Returns:

The created obj.

Return type:

Tune

Raises:

AsserationError – Invalid string format.

property value

The string value that will be used to

get response.

Format:

imsak,fajr,sunrise,dhuhr,asr,maghrib,sunset,isha,midnight

Type:

str

Parameters Related

Parameters

class aladhan.Parameters

Class to make an obj that will be used as a defaults param in getters.

Parameters:

• method (methods.Method or int) –

  A prayer time calculation method, you can look into all methods from Client.get_all_methods().

  Default: ISNA (Islamic Society of North America).

• tune (Optional[Tune]) – To offset returned timings. Default: Tune()

• school (int or School) – 0 for Shafi (standard), 1 for Hanafi. Default: Shafi

• midnightMode (int or MidnightMode) – 0 for Standard (Mid Sunset to Sunrise), 1 for Jafari (Mid Sunset to Fajr). Default: Standard

• timezonestring (Optional[str]) –

  A valid timezone name as specified on https://www.php.net/manual/en/timezones.php

  Example: Europe/London.

  Calculated using the co-ordinates provided by default.

  This should be used only in getters that uses co-ordinates or it will be ignored.

  New in v0.2.

• latitudeAdjustmentMethod (int or LatitudeAdjustmentMethod) –

  Method for adjusting times higher latitudes. For instance, if you are checking timings in the UK or Sweden.

  1 - Middle of the Night 2 - One Seventh 3 - Angle Based

  Default: Angle Based

• adjustment (int) – Number of days to adjust hijri date(s) Default: 0

• shafaq (str or Shafaq) –

  Which Shafaq to use if the method is Moonsighting Commitee Worldwide. Default: ‘general’

  New in v1.2.0

method

Method id.

Type:

int

method_params

Method’s parameters. None if method wasn’t custom.

New in v0.2.

Type:

Optional[dict[str, int or “null”]]

tune

Tune Value.

Type:

str

school

Type:

int

midnightMode

Type:

int

timezonestring

New in v0.2.0

Type:

Optional[str]

latitudeAdjustmentMethod

Type:

int

adjustment

Type:

int

shafaq

New in v1.2.0

Type:

str

Raises:

• InvalidMethod – Method id passed was not in 0-15, Or passed an integer (99) instead of Method obj for a custom method use.

• InvalidTune – Tune with a bad value was passed.

• InvalidSchool –

• InvalidMidnightMode –

• InvalidTimezone –

• InvalidLatAdjMethod –

• InvalidAdjustment –

• InvalidShafaq –

Timings Date Argument

class aladhan.TimingsDateArg

Class to make an obj that will be used as a date param in timings getters

Parameters:

date (Optional[int or str) –

or datetime.datetime]

Can be either int representing the UNIX format or a str in DD-MM-YYYY format or a datetime obj. Default: current date.

date

A date string in DD-MM-YYYY format.

Type:

str

Raises:

AsserationError – Invalid date string format.

Calendar Date Argument

class aladhan.CalendarDateArg

Class to make an obj that will be used as a date param in calendar

getters

Parameters:

• year (int) – Required argument for calendar’s year.

• month (Optional[int]) – If this was not giving, or 0 was giving instead it will return a whole year calendar instead which is set to by default

• hijri (bool) – whether year is a hijri year or not. Default: False

year

Calendar’s year.

Type:

int

month

Calendar’s month, set to 0 if it wasn’t given.

Type:

int

annual

Whether a year calender going to be returned ot not. “true” if month was not given otherwise “false”.

Type:

str

hijri

Whether year given is a hijri year or not.

Type:

bool

Raises:

ValueError – Month passed is not in 1-12 range.

Calculation Methods

Method

class aladhan.Method

Represents a Method Calculation obj. Can be used to create a Custom Method. To make a custom method:

params = {
    "fajr": ...,  # can be either an `int` or "null",                 if it was not giving it will be set to "null".
    "maghrib": ...,
    "isha": ...
}
# id must be 99. Name param doesn't effect.
custom_method = Method("Custom", 99, params=params)

name

Method name.

Type:

str

id

Method id that will be used to get response. Can be only from 0 to 15.

Type:

int

property params

Method parameters.

Changed in v1.0.0 to a property.

property params_str

A string in “fajr,maghrib,isha” format.

New in v1.0.0

Available Methods

Method	ID	Name
JAFARI	0	Shia Ithna-Ashari, Leva Institute, Qum
KARACHI	1	University of Islamic Sciences, Karachi
ISNA	2	Islamic Society of North America (ISNA)
MWL	3	Muslim World League
MAKKAH	4	Umm Al-Qura University Makkah
EGYPT	5	Egyptian General Authority of Survey
TEHRAN	7	Institute of Geophysics, University of Tehran
GULF	8	Gulf Region
KUWAIT	9	Kuwait
QATAR	10	Qatar
SINGAPORE	11	Majlis Ugama Islam Singapura, Singapore
FRANCE	12	Union Organization Islamic de France
TURKEY	13	Diyanet u0130u015fleri Bau015fkanlu0131u011fu0131, Turkey
RUSSIA	14	Spiritual Administration of Muslims of Russia
MOONSIGHTING	15	Moonsighting Committee Worldwide (Moonsighting.com)

Note

• There is no 6 (method 6 is apparently same as 2).

• Method 15 requires a shafaq parameter.

all_methods: dict[int, Method]

A dict of each id and its method.

Data Classes

Data

class aladhan.Data

Main class Representing the data returned from a timings request to API

Do not create this class yourself. Only get it through a getter.

meta

Represents the meta part.

Type:

Meta

date

Represents the date part.

Type:

Date

timings

Represents the timings part.

Type:

Timings

client

Represents the client that the Data were fetched from.

Type:

Client

Meta

class aladhan.Meta

Represents the meta that is in returned Data

Do not create this class yourself. Only get it through a getter.

data

Original fetched Data.

Type:

Data or NextPrayerData

longitude

Longitude coordinate.

Type:

float

latitude

Latitude coordinate.

Type:

float

timezone

Used timezone to calculate.

Type:

pytz.UTC

method

Calculation Method. None if it was a custom method.

Type:

Optional[Method]

latitudeAdjustmentMethod

Type:

str

midnightMode

Type:

str

school

Type:

str

offset

Used offset to tune timings.

Type:

Tune

property parameters

returns a Parameters obj

Warning

This will set method to ISNA if method was custom, and it will always set adjustment to 0.

Type:

Parameters

Base Date

class aladhan.BaseDate

Do not create this class yourself. Only get it through a getter.

New in v1.2.0

readable

Date in readable format. None if it wasn’t from a timings getter.

Type:

Optional[str]

timestamp

Date in UNIX format. None if it wasn’t from a timings getter.

Type:

Optional[int]

Date

class aladhan.Date

Represents the date that is in returned Data

Do not create this class yourself. Only get it through a getter.

data

Original fetched Data. None if it wasn’t from a timings getter.

Changed in v1.1.0: changed to Optional

Type:

Optional[Data]

readable

Date in readable format. None if it wasn’t from a timings getter.

Changed in v1.1.0: changed to Optional

Type:

Optional[str]

timestamp

Date in UNIX format. None if it wasn’t from a timings getter.

Changed in v1.1.0: changed to Optional

Type:

Optional[int]

gregorian

Gregorian date.

Type:

DateType

hijri

Hijri date.

Type:

DateType

DateType

class aladhan.DateType

A class for gregorian/hijri date.

Do not create this class yourself. Only get it through a getter.

name

gregorian or hijri.

Type:

str

date

Date string.

Type:

str

format

Date’s format

Type:

str

day

Date’s day.

Type:

int

weekday

A dict with 2 keys, “en” and “ar” for hijri and only 1 key “en” for gregorian.

Type:

dict[str, str]

month

A dict with 3 keys “number”, “en”, “ar” for hijri and 2 keys “number”, “en” for gregorian.

Type:

dict[str, int or str]

year

Date’s year.

Type:

int

designation

A dict with 2 keys, “abbreviated” and “expanded”.

Type:

dict[str, str]

holidays

A list of holidays might be empty for hijri, always None for gregorian.

Type:

Optional[list of str]

lunarSighting

A boolean for gregorian and None for hijri.

New in v1.2.2

Type:

Optional[bool]

lunarSighting

A boolean for hijri and None for gregorian.

New in v1.2.2

Type:

Optional[bool]

method

A string for hijri and None for gregorian.

New in v1.2.2

Type:

Optional[str]

Ism

class aladhan.Ism

Represents an Ism obj.

Do not create this class yourself. Only get it through a getter.

name

The name in arabic.

Type:

str

transliteration

The transliteration of the name.

Type:

str

number

Ism’s number/id.

Type:

int

en

The name in english.

Type:

str

New in v0.1.3

Qibla

class aladhan.Qibla

Represents a Qibla obj.

Do not create this class yourself. Only get it through a getter.

longitude

Longitude coordinate.

Type:

float

latitude

Latitude coordinate.

Type:

float

direction

Qibla direction.

Type:

float

New in v0.1.3

Enums

class aladhan.enums.Schools(value)

Available schools

STANDARD = 0

SHAFI = 0

HANAFI = 1

class aladhan.enums.MidnightModes(value)

Available midnight modes

STANDARD = 0

JAFARI = 1

class aladhan.enums.LatitudeAdjustmentMethods(value)

Available latitude adjustment methods

MIDDLE_OF_THE_NIGHT = 1

ONE_SEVENTH = 2

ANGLE_BASED = 3

class aladhan.enums.Shafaq(value)

An enumeration.

GENERAL = 'general'

RED = 'ahmer'

WHITE = 'abyad'

Exceptions

The following exceptions are thrown by the library.

exception aladhan.exceptions.AladhanException(message='')

Base exception class for aladhan.py

Ideally speaking, this could be caught to handle any exceptions

thrown from this library.

message

Exception’s message.

Type:

str

exception aladhan.exceptions.HTTPException(response, message='')

Exception that’s thrown when an HTTP request operation fails.

response

API’s response.

Type:

dict

code

Response’s code.

Type:

int

exception aladhan.exceptions.BadRequest(response, message='')

Exception that’s thrown for when status code 400 occurs.

exception aladhan.exceptions.TooManyRequests(response, message='')

Exception that’s thrown for when status code 429 occurs.

Note

Current API’s rate limit is 14 requests/s.

New in v1.2.0

exception aladhan.exceptions.InternalServerError(response, message='')

Exception that’s thrown for when status code 500 occurs.

exception aladhan.exceptions.InvalidArgument(message='')

Exception that’s thrown when an argument to a function is invalid some way (e.g. wrong value or wrong type).

exception aladhan.exceptions.InvalidMethod(message='')

Exception that’s thrown when method argument is invalid.

exception aladhan.exceptions.InvalidTune(message='')

Exception that’s thrown when tune argument is invalid.

exception aladhan.exceptions.InvalidSchool(message='')

Exception that’s thrown when school argument is invalid.

exception aladhan.exceptions.InvalidMidnightMode(message='')

Exception that’s thrown when midnight mode argument is invalid.

exception aladhan.exceptions.InvalidTimezone(message='')

Exception that’s thrown when timezone argument is invalid.

exception aladhan.exceptions.InvalidLatAdjMethod(message='')

Exception that’s thrown when latitude adjustment method argument is invalid.

exception aladhan.exceptions.InvalidAdjustment(message='')

Exception that’s thrown when adjustment argument is invalid.

exception aladhan.exceptions.InvalidShafaq(message='')

Exception that’s thrown when shafaq argument is invalid.

Exception Hierarchy

• Exception

  • AladhanException

    • HTTPException

      • BadRequest

      • TooManyRequests

      • InternalServerError

    • InvalidArgument

      • InvalidMethod

      • InvalidTune

      • InvalidSchool

      • InvalidMidnightMode

      • InvalidTimezone

      • InvalidLatAdjMethod

      • InvalidAdjustment

      • InvalidShafaq