AlAdhan-API-Documentation.md

AlAdhan API Documentation

الأذَان

Overview

The AlAdhan API is a collection of RESTful web services providing accurate Islamic prayer times, Hijri calendar conversions, Qibla direction calculations, and other useful Islamic data. The API is designed to be easy to use and integrate into applications, websites, and other services.

API Base URL: https://api.aladhan.com/v1

Table of Contents

• Quick Start
• Authentication
• API Endpoints
  • Prayer Times
  • Hijri Calendar
  • Qibla Direction
  • Asma Al-Husna
  • Geo Information
  • Date and Time
• Response Format
• Error Handling
• API Rate Limiting
• OpenAPI Documentation
• Support

Quick Start

Here's a simple example of how to get prayer times for a specific location:

curl -X GET "https://api.aladhan.com/v1/timingsByCity?city=London&country=United%20Kingdom&method=2"

This will return prayer times for London, UK using the ISNA calculation method.

Authentication

Most of the AlAdhan API endpoints are freely accessible without authentication. However, some geocoding features may require an API key from 7x.ax for unmasked coordinates.

API Endpoints

Prayer Times

Get Prayer Times

Get prayer times for a specific date and location using coordinates.

GET /timings/{date}

Parameters:

• date: Date in YYYY-MM-DD format (optional, defaults to current date)
• latitude: Latitude coordinate
• longitude: Longitude coordinate
• method: Calculation method ID (1-15, default: 3)
• shafaq: Shafaq parameter for Isha calculation ('general', 'ahmer', 'abyad')
• tune: Fine-tune timings in minutes
• school: Juristic school for Asr (0: Shafi, 1: Hanafi)
• midnightMode: Midnight calculation mode (0: Standard, 1: Jafari)
• timezonestring: Timezone string (e.g., 'Europe/London')
• latitudeAdjustmentMethod: Method to adjust for higher latitudes
• iso8601: Boolean to return times in ISO 8601 format

Example Request:

GET /timings/2023-12-01?latitude=51.508515&longitude=-0.1254872&method=2

Get Prayer Times By Address

Get prayer times based on an address string.

GET /timingsByAddress/{date}

Parameters:

• date: Date in YYYY-MM-DD format (optional, defaults to current date)
• address: Address string
• Other parameters as above

Example Request:

GET /timingsByAddress/2023-12-01?address=Baker%20Street,%20London,%20UK&method=2

Get Prayer Times By City

Get prayer times based on city and country.

GET /timingsByCity/{date}

Parameters:

• date: Date in YYYY-MM-DD format (optional, defaults to current date)
• city: City name
• country: Country name or code
• Other parameters as above

Example Request:

GET /timingsByCity/2023-12-01?city=Dubai&country=AE&method=8

Get Next Prayer

Get the next prayer time for a specific location.

GET /nextPrayer/{date}

Parameters:

• Similar to the timings endpoint

Get Prayer Times Calendar

Get prayer times for an entire month or year.

GET /calendarByCity/{year}/{month}

Parameters:

• year: Year (4-digit format)
• month: Month (1-12)
• city: City name
• country: Country name or code
• Other calculation parameters as above

Example Request:

GET /calendarByCity/2023/12?city=Makkah&country=SA&method=4

Get Prayer Time Calculation Methods

Get all available calculation methods for prayer times.

GET /methods

Hijri Calendar

Convert Gregorian to Hijri Date

Convert a Gregorian date to Hijri (Islamic) date.

GET /gToH/{date}

Parameters:

• date: Gregorian date in DD-MM-YYYY format

Example Request:

GET /gToH/04-03-2025

Convert Hijri to Gregorian Date

Convert a Hijri date to Gregorian date.

GET /hToG/{date}

Parameters:

• date: Hijri date in DD-MM-YYYY format

Example Request:

GET /hToG/15-08-1446

Get Hijri Calendar for Month

Get the Hijri calendar for a specific Gregorian month and year.

GET /gToHCalendar/{month}/{year}

Parameters:

• month: Gregorian month (1-12)
• year: Gregorian year

Example Request:

GET /gToHCalendar/3/2025

Get Islamic Holidays

Get Islamic holidays for a Hijri year.

GET /islamicHolidaysByHijriYear/{year}

Parameters:

• year: Hijri year

Example Request:

GET /islamicHolidaysByHijriYear/1446

Get Current Islamic Month/Year Information

GET /currentIslamicMonth
GET /currentIslamicYear

Get Islamic Months

Get list of Islamic months.

GET /islamicMonths

Qibla Direction

Get the Qibla direction (degrees from North) for a specific location.

GET /qibla/{latitude}/{longitude}

Parameters:

• latitude: Latitude coordinate
• longitude: Longitude coordinate

Example Request:

GET /qibla/51.508515/-0.1254872

Asma Al-Husna

Get the 99 names of Allah.

GET /asmaAlHusna
GET /asmaAlHusna/{number}

Parameters:

• number: Optional, specific name number (1-99)

Example Request:

GET /asmaAlHusna/1

Geo Information

Get geographical information for address, city, or coordinates.

GET /addressInfo

Parameters:

• address: Address string
• x7xapikey: Optional 7x API key for unmasked coordinates

Example Request:

GET /addressInfo?address=Kaaba,%20Makkah,%20Saudi%20Arabia

Date and Time

Various date and time utilities.

GET /currentTimestamp
GET /currentTimestampByCity

Parameters for currentTimestampByCity:

• city: City name
• country: Country name or code

Response Format

All API responses are in JSON format with the following structure:

{
  "code": 200,
  "status": "OK",
  "data": {
    // Response data specific to the endpoint
  }
}

Sample Prayer Times Response

{
  "code": 200,
  "status": "OK",
  "data": {
    "timings": {
      "Fajr": "05:21",
      "Sunrise": "06:58",
      "Dhuhr": "12:12",
      "Asr": "15:11",
      "Sunset": "17:25",
      "Maghrib": "17:25",
      "Isha": "19:02",
      "Imsak": "05:11",
      "Midnight": "00:12",
      "Firstthird": "21:16",
      "Lastthird": "03:08"
    },
    "date": {
      "readable": "01 Dec 2023",
      "timestamp": "1701417600",
      "gregorian": {
        "date": "01-12-2023",
        "format": "DD-MM-YYYY",
        "day": "01",
        "weekday": {
          "en": "Friday"
        },
        "month": {
          "number": 12,
          "en": "December"
        },
        "year": "2023",
        "designation": {
          "abbreviated": "AD",
          "expanded": "Anno Domini"
        }
      },
      "hijri": {
        "date": "17-05-1445",
        "format": "DD-MM-YYYY",
        "day": "17",
        "weekday": {
          "en": "Al Juma'a",
          "ar": "الجمعة"
        },
        "month": {
          "number": 5,
          "en": "Jumādá al-ūlá",
          "ar": "جُمادى الأولى"
        },
        "year": "1445",
        "designation": {
          "abbreviated": "AH",
          "expanded": "Anno Hegirae"
        },
        "holidays": []
      }
    },
    "meta": {
      "latitude": 51.508515,
      "longitude": -0.1254872,
      "timezone": "Europe/London",
      "method": {
        "id": 2,
        "name": "Islamic Society of North America (ISNA)",
        "params": {
          "Fajr": 15,
          "Isha": 15
        },
        "location": {
          "latitude": 39.70421229999999,
          "longitude": -86.39943869999999
        }
      },
      "latitudeAdjustmentMethod": "ANGLE_BASED",
      "midnightMode": "STANDARD",
      "school": "STANDARD",
      "offset": {
        "Imsak": 0,
        "Fajr": 0,
        "Sunrise": 0,
        "Dhuhr": 0,
        "Asr": 0,
        "Maghrib": 0,
        "Sunset": 0,
        "Isha": 0,
        "Midnight": 0
      }
    }
  }
}

Error Handling

When an error occurs, the API returns a JSON response with an appropriate HTTP status code and an error message:

{
  "code": 400,
  "status": "Bad Request",
  "data": "Invalid coordinates. Latitude and Longitude are required."
}

Common error codes:

• 400: Bad Request - Check the request parameters
• 404: Not Found - The requested resource was not found
• 500: Internal Server Error - Something went wrong on the server

API Rate Limiting

The AlAdhan API currently does not enforce strict rate limits but requests excessive usage to be avoided. For high-volume applications, consider caching responses or contacting the API administrators.

OpenAPI Documentation

The AlAdhan API provides OpenAPI documentation available at the following endpoints:

• Prayer Times: /v1/documentation/openapi/prayer-times/yaml
• Islamic Calendar: /v1/documentation/openapi/islamic-calendar/yaml
• Qibla: /v1/documentation/openapi/qibla/yaml
• Asma Al-Husna: /v1/documentation/openapi/asma-al-husna/yaml
• Geo: /v1/documentation/openapi/geo/yaml
• Date and Time: /v1/documentation/openapi/date-time/yaml

Support

For questions, issues, or feature requests, please visit:

• GitHub Repository
• AlAdhan.com Website

License

The AlAdhan API is open-source and available under the GPL-3.0 license.

---

Last Updated: March 4, 2025 by Zxce3

This documentation is provided as a comprehensive guide to the AlAdhan API but may not cover all features or future updates. Always refer to the official repository for the most up-to-date information.