Skip to content

pakjiddat/Islam-Companion-Web-Api

Repository files navigation

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

The goal of the Islam Companion Web API is to help users developed 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 8 API functions for fetching Quranic data
  • It provides 7 API functions for fetching 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']

Download data

Click here to download the Hadith database in .sql format for MySQL server. Click here to download the Hadith database in .db format for SQLite3

Click here to download the Quranic database in .db format for SQLite3

Frequently asked questions

  • What is the Islam Companion Web API. It is a RESTFul API for accessing Holy Quran and Hadith data
  • What can I do with the Islam Companion Web API. You can develop web based applications that present Holy Quran and Hadith data to the user. The Islam Companion Api can work as the backend of your application.
  • Which languages are supported by the Islam Companion Web API. Click Here
  • What functions are provided by the Islam Companion Api. Please read the documentation.
  • From where does the API get its data. The Islam Companion API uses Holy Quran translations from http://tanzil.net/trans/. It uses Hadith data from http://hadithcollection.com/ and https://www.quranurdu.com/Ahadith/.
  • How do I use the API. To use the API, you have to make HTTP POST request to your web server. Please see following sample code in Php language.

Sample Code

<?php

$data = array(
    'language' => 'English',
    'narrator' => 'Mohammed Marmaduke William Pickthall'
);
 
// Prepare new cURL resource
$ch = curl_init('[your-website-name]/api/get_random_verses');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLINFO_HEADER_OUT, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
 
// Submit the POST request
$result = curl_exec($ch);
 
// Close cURL session handle
curl_close($ch);

// json decode the response
$result = json_decode($result, true);

// Print the result
print_r($result);
?>

Usage

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

To test the API, use the following url: [your-server]/api/ for making API requests. All API requests must be of type HTTP POST and should include the required API parameters.

API calls for fetching Holy Quran data

Name Description Url Parameters Response
Get Suras In Division Returns the list of suras for the given division and division number /api/get_suras_in_division
  • 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
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
Get Ruku List It provides the start and end ruku numbers for the given division, division number and sura /api/get_ruku_list
  • 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
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
Get Verses It returns the arabic text and translation for the given verses /api/get_verses
  • start_ayat. The start ayat number
  • end_ayat. The end ayat number
  • language. The language for the verse text
  • narrator. The translator name
  • sura. The sura number
The list of required ayas
  • arabic_text. The arabic text
  • translation. The translated text
  • sura_id. The sura id
  • sura_name. The sura name
  • ayat. The ayat number
Get Random Verses It returns the text for a random ruku along with meta data /api/get_random_verses
  • language. The language for the verse text
  • narrator. The translator name
The verse data
  • arabic. The verse text in arabic
  • translation. The translated text
  • meta_data. The ruku meta data
Get Holy Quran Navigator Configuration It generates the navigator configuration data for the given action /api/get_quran_nav_config
  • 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
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
Get Languages It returns the list of all supported languages /api/get_languages None The list of all supported languages
Get Narrators It returns the list of all supported narrators for the given language /api/get_narrators
  • language. The language for the verse text
The list of all supported narrators
Search Ayat It returns list of ayas that contain the given text /api/search_ayat
  • is_random. Indicates if random search results should be fetched
  • language. Custom the language for the verse text
  • narrator. The translator name
  • page_number. The search results page number
  • results_per_page. The number of results per page
  • search_text. The search text
Contains the search results and total result count
  • search_results. The verse data that contains the given text
  • result_count. The total number of results

API calls for fetching Hadith data

Name Description Url Parameters Response
Get Hadith Books It returns the list of Hadith books for the given Hadith source /api/get_hadith_books
  • language. The hadith language
  • source. The hadith source for which the books need to be fetched
The list of Hadith books
  • id. The hadith book id
  • book. The hadith book
Get Hadith Titles It fetches list of Hadith book titles for the given Hadith book and source /api/get_hadith_titles
  • book_id. The hadith book id
  • language. The hadith language
The list of hadith book titles
  • id. The hadith title id
  • title. The hadith title
Get Hadith It fetches list of Hadith text for the given Hadith title and book id /api/get_hadith
  • language. The hadith language
  • title_id. The hadith title id
The list of Hadith
  • text. The hadith text
  • title. The hadith title
  • title_id. The hadith title id
  • book_id. The hadith book id
  • book. The hadith book name
  • number. The hadith number
  • source. The hadith source
Get Random Hadith It fetches list of random hadith text /api/get_random_hadith
  • hadith_count. The number of hadith to fetch
  • language. The hadith language
The hadith text
  • text. The hadith text
  • source. The hadith source
  • book. The hadith book name
  • number. The hadith number
Get Hadith Sources It fetches list of hadith sources for the given language /api/get_hadith_sources
  • language. The hadith language
The list of hadith sources
  • hadith_sources. The hadith sources
Get Hadith Navigator Configuration It returns the navigator configuration for given navigator action /api/get_hadith_nav_config
  • 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
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
Search Hadith It returns list of hadith that contain the given text /api/search_hadith
  • is_random. Indicates if random search results should be fetched
  • language. The language for the hadith text
  • page_number. The search results page number
  • results_per_page. The number of results per page
  • search_text. The search text
Contains the search results and total result count
  • search_results. The search results
  • result_count. The total number of results