Islam Companion Web API

Posted on 18-03-2019 by Nadir Latif

Islam Companion Web API

Introduction

The "Islam Companion Web API" project is a RESTFul API (Application Programming Interface) that allows users to add Holy Quran and Hadith data to their applications. It provides Holy Quran translation in 42 languages. Following languages are supported: Amharic, Arabic, Bosnian, Bengali, Bulgarian, Amazigh, Czech, German, Divehi, Spanish, English, Persian, French, Hindi, Hausa, Indonesian, Italian, Japanese, Korean, Kurdish, Malayalam, Malay, Dutch, Norwegian, Portuguese, Polish, Russian, Romanian, Swedish, Somali, Sindhi, Albanian, Swahili, Turkish, Tajik, Tamil, Tatar, Thai, Uzbek, Urdu, Uyghur and Chinese. Hadith translation is provided in Urdu, English and Arabic languages

An example of a website that uses the Islam Companion Web API is the Islam Companion website. The Holy Quran Reader and Hadith Reader were developed using the Islam Companion Web API

The goal of the Islam Companion Web API is to help users develop web applications that promote knowledge about Islam.

Features

The Islam Companion Web API has the following features:

  • It provides translations of Holy Quran in 42 languages
  • It provides translations of Hadith in Urdu, English and Arabic languages
  • It provides meta data about Holy Quran and Hadith data
  • The source code is available under GPL License
  • The source code is well commented and easy to update

Requirements

The Islam Companion Web API requires Php >= 7.2. It also requires MySQL server >= 5.6.

Installation

The following steps can be used to install the "Islam Companion Web API" project on your own server:

  • Download the source code from GitHub
  • Move the source code to the document root of a virtual host
  • Download the contents of the database from: here
  • Extract the downloaded file
  • Create a database and import the contents of the sql file to the database. Note down the credentials used for connecting to the database
  • Enter the database credentials in the file api/config/RequiredObjects.php
  • In the file: api/Config.php, on line 37 enter the domain names that will be used to access the api
  • Customize the following variables in the file: api/config/General.php. $config['app_name'], $config['dev_mode'] and $config['site_url']

Usage

The Islam Companion Web API supports the following functions. All function response values are in JSON format.

API calls for fetching Holy Quran data
  1. Name: get_suras_in_division
    Description: Returns the list of suras for the given division and division number
    Url: /api/get_suras_in_division
    Parameters:
    • division. The division name. It can be hizb,juz,page,manzil,ruku
    • div_num. The division number. It should be a number 1 and 604
    Response: The names of all the suras that are in the given division:
    • tname. The english name of the sura
    • ename. A brief description of the sura in English
    • sindex. The sura number. It should be a number 1 and 114
  2. Name: get_ruku_list
    Description: It provides the start and end ruku numbers for the given division, division number and sura
    Url: /api/get_ruku_list
    Parameters:
    • division. The division name. It can be hizb,juz,page,manzil,ruku
    • div_num. The division number. It should be a number 1 and 604
    • sura. The sura number. It should be a number 1 and 114
    Response: The start and end ruku numbers
    • start_ruku. The start sura ruku number. It should be a number 1 and 40
    • end_ruku. The end sura ruku number. It should be a number 1 and 40
  3. Name: get_verses
    Description: It returns the arabic text and translation for the given verses
    Url: /api/get_verses
    Parameters:
    • end_ayat. The end ayat number
    • language. The language for the verse text
    • narrator. The translator name
    • start_ayat. The start ayat number
    • sura. The sura number
    Response: The list of required ayas
    • arabic_text. The arabic text
    • translated_text. The translated text
  4. Name: get_random_verses
    Description: It returns the text for a random ruku along with meta data
    Url: /api/get_random_verses
    Parameters:
    • language. The language for the verse text
    • narrator. The translator name
    Response: The verse data
    • text. The verse text
    • meta_data. The ruku meta data
  5. Name: get_holy_quran_navigator_configuration
    Description: It generates the navigator configuration data for the given action
    Url: /api/get_holy_quran_navigator_configuration
    Parameters:
    • action. The action taken by the user
    • div_num. The current division number
    • division. The current division
    • sura. The current sura
    • sura_ruku. The current sura ruku
    Response: The updated Navigator configuration data
    • sura. The new sura
    • sura_ruku. The new ruku id
    • start_ayat. The new start ayat
    • end_ayat. The new end ayat
    • div_num. The new division number
    • audiofile. The base audio file name
API calls for fetching Hadith data
  1. Name: get_hadith_books
    Description: It returns the list of Hadith books for the given Hadith source
    Url: /api/get_hadith_books
    Parameters:
    • language. The hadith language
    • source. The hadith source for which the books need to be fetched
    Response: The list of Hadith books
    • id. The hadith book id
    • book. The hadith book
  2. Name: get_hadith_titles
    Description: It fetches list of Hadith book titles for the given Hadith book and source
    Url: /api/get_hadith_titles
    Parameters:
    • book_id. The Hadith book id
    Response: The list of Hadith book titles
    • id. The Hadith title id
    • title. The Hadith title
  3. Name: get_hadith
    Description: It fetches list of Hadith text for the given Hadith title and book id
    Url: /api/get_hadith
    Parameters:
    • language. The Hadith language
    • title_id. The Hadith title id
    Response: The list of Hadith
    • text. The Hadith text
    • title. The Hadith title
  4. Name: get_random_hadith
    Description: It fetches list of random hadith text
    Url: /api/get_random_hadith
    Parameters:
    • hadith_count. The number of hadith to fetch
    • language. The hadith language
    Response: The Hadith text
    • source. The hadith source
    • book. The hadith book name
    • hadith_number. The hadith number
  5. Name: get_hadith_navigator_configuration
    Description: It returns the navigator configuration for given navigator action
    Url: /api/get_hadith_navigator_configuration
    Parameters:
    • action. The action taken by the user
    • book_id. The Hadith book id
    • language. The Hadith language
    • source. The Hadith source
    • title_id. The Hadith book title id
    Response: The updated Navigator configuration data
    • source. The new Hadith source
    • book_id. The new Hadith book id
    • title_id. The new Hadith book title id

Leave a Comment: