API Reference

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

Client

class aladhan.Client[source]

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

import aladhan

client = aladhan.Client()
times = client.get_timings_by_address("New York")
print(times)
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()[source]

Closes the connection.

get_next_prayer_by_address(address, date=None, params=None)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]
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)[source]
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()[source]

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)[source]

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)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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()[source]
Returns

Api’s status.

Return type

dict

Raises

InternalServerError – Status Check Failed.

get_special_days()[source]

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()[source]

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.

Data Classes

Data

class aladhan.Data[source]

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[source]

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[source]

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[source]

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[source]

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]

Ism

class aladhan.Ism[source]

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[source]

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)[source]

Available schools

STANDARD = 0
SHAFI = 0
HANAFI = 1
class aladhan.enums.MidnightModes(value)[source]

Available midnight modes

STANDARD = 0
JAFARI = 1
class aladhan.enums.LatitudeAdjustmentMethods(value)[source]

Available latitude adjustment methods

MIDDLE_OF_THE_NIGHT = 1
ONE_SEVENTH = 2
ANGLE_BASED = 3
class aladhan.enums.Shafaq(value)[source]

An enumeration.

GENERAL = 'general'
RED = 'ahmer'
WHITE = 'abyad'

Exceptions

The following exceptions are thrown by the library.

exception aladhan.exceptions.AladhanException(message='')[source]

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=None)[source]

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=None)[source]

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

exception aladhan.exceptions.TooManyRequests(response, message=None)[source]

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=None)[source]

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

exception aladhan.exceptions.InvalidArgument(message='')[source]

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='')[source]

Exception that’s thrown when method argument is invalid.

exception aladhan.exceptions.InvalidTune(message='')[source]

Exception that’s thrown when tune argument is invalid.

exception aladhan.exceptions.InvalidSchool(message='')[source]

Exception that’s thrown when school argument is invalid.

exception aladhan.exceptions.InvalidMidnightMode(message='')[source]

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

exception aladhan.exceptions.InvalidTimezone(message='')[source]

Exception that’s thrown when timezone argument is invalid.

exception aladhan.exceptions.InvalidLatAdjMethod(message='')[source]

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

exception aladhan.exceptions.InvalidAdjustment(message='')[source]

Exception that’s thrown when adjustment argument is invalid.

exception aladhan.exceptions.InvalidShafaq(message='')[source]

Exception that’s thrown when shafaq argument is invalid.