بِسْمِ اللَّـهِ الرَّحْمَـٰنِ الرَّحِيمِ

Contents

• Alquran
• Demo
• Usage
  • ~Edition~
  • ~Quran~
  • ~Juz~
  • ~Surah~
  • ~Ayah~
  • ~Search~
  • ~Manzil~
  • ~Ruku~
  • ~Page~
  • ~Hizb~
  • ~Sajda~
• Improve Documentation
• Refactor Classes to Be non-static, to facilitate .NET management
• Add Unit Testing Class
• Note About ~Meta~

Alquran

.NET lightweight Quran library using the alquran.cloud v1 APIs.

• Dependencies:
  • RestSharp (>= 107.3.0)
  • RestSharp.Serializers.NewtonsoftJson (>= 107.3.0)

This release was built using .NET 6

Demo

using alquran;
var e1 = AlQuranV1.Quran(); //getting all of Quran
var e2 = AlQuranV1.Quran("en.asad "); //getting Muhammad Asad's edition of the Holy Quran
var e3 = AlQuranV1.Quran("ar.alafasy "); // getting Mishary Alafasy's recitation of the Quran

Usage

Edition

All calls of this methods give you an IEnumerable object of editions describing the filte editions. From this object, you need to use the identifier to get data from other endpoints in this API. For any of the endpoints that require an edition identifier, if you do not specify one, ‘quran-uthmani’ is used and returns the Arabic text of the Holy Quran.

IEnumerable<Edition>? Editions(string format, string lang, string type)

Parameters

• format: specify a format. ‘text’ or ‘audio.
• lang: a 2 digit language code. Example: ‘en’, ‘fr’, etc.
• type: a valid type. Example - ‘versebyverse’, ‘translation’ etc.

Cases

Lists all editions for a given language:

IEnumerable<Edition>? Editions(string lang)

Lists all editions for a given format:

IEnumerable<Edition>? Editions(string format)

Lists all editions for a given type:

IEnumerable<Edition>? Editions(string type)

Required Parameters

None

Default Values

Returns a list of all available editions

Example

var e = AlQuranV1.Editions("audio", "fr", "versebyverse") // Lists all audio editions in french of the versebyverse type

Return Type

This methods always returns an IEnumerable<edition>

Quran

Returns a complete Quran edition in the audio or text format

Quran? Quran(string edition)

Parameters

• edition: an edition identifier. Example: en.asad for Muhammad Asad’s english translation

Cases

Quran? Quran()

Returns the text of the Holy Quran in the quran-uthmani edition.

Quran? Quran(string edition)

Returns a complete Quran edition.

Default Values

Returns the text of the Holy Quran in the quran-uthmani edition.

Required Parameters

None

Example

var e1 = AlQuranV1.Quran(); // Returns Muhammad Asad's translation of the Holy Quran
var e2 = AlQuranV1.Quran("en.asad "); // Returns the text of the Holy Quran
var e3 = AlQuranV1.Quran("ar.alafasy "); // Returns Mishary Alafasy's recitation of the Quran

Return Type

An object of type Quran

Juz

The Quran has 30 Juz. You can get the text for each Juz using the method below.

Juz? Juz(int juz, string edition, int offset, int limit)

Parameters

• juz: number of juz.
• edition: an edition identifier. Example: en.asad for Muhammad Asad’s english translation.
• offset: offset ayahs in a juz by the given number.
• limit: number of ayahs that the response will be limited to.

Cases

Juz? Juz(int juz, string edition)

Returns an object of juz from edition edition of the Holy Quran

Juz? Juz(int juz, string edition, int offset, int limit)

Required Parameters

• juz: number of juz

Example

var e1 = AlQuranV1.Juz(30, "en.asad");
var e2 = AlQuranV1.Juz(30, "quran-uthmani");
var e3 = AlQuranV1.Juz(1, "quran-uthmani", 3, 10);

Return Values

An object of type Juz

Surah

Get a single Surah in one object or in a list with its other ports in other editions of the Holy Quran.

object? Surah(int surah, string edition, int offset, int limit)

Parameters

• surah: number of surah
• edition: an edition identifier. Example: en.asad for Muhammad Asad’s english translation.
• offset: offset ayahs in a juz by the given number.
• limit: number of ayahs that the response will be limited to.

Cases

object? Surah(int surah , string edition , int offset , int limit )

Returns an object (castable to Surah object) of the Surah with number surah, edition edition and offset offset to the limit limit.

object? Surah(int surah)

Returns an object (castable to Surah object) of Surah with number surah and edition quran-simple. It will return an object castable to IEnumerable<Surah> if edition is more than 1 edition.

object? Surah()

Returns an object (castable to IEnumerable<Surah> object) of all Surahs of the holy Quran

Default Value

Returns an object (castable to IEnumerable<Surah> object) of all Surahs of the holy Quran

Required Parameters

None

Example

var e1 = AlQuranV1.Surah() as IEnumerable<Surah>; // all Surahs of Quran
var e2 = AlQuranV1.Surah(114, "ar.alafasy") as Surah; // Returns Mishary Alafasy's recitation of Surat An-Naas
var e3 = AlQuranV1.Surah(3, offset: 4, limit: 7) as Surah; // - Returns verses 2-4 of Surah Al-Fatiha
var e4 = AlQuranV1.Surah(114, "quran-uthmani,en.asad,en.pickthall") as IEnumerable<Surah>; //  Returns Surat An-Naas from 3 editions: Simple Quran, Muhammad Asad and Marmaduke Pickthall

Return Value

object?

Note

Since the Surah API may return a single Surah, as in example e2 as well it might returns a list of Surahs, as in examples e1, e4, it return an object type which can be safely casted to whichever type.

Ayah

Get a single Ayah in one object or in a list with its other ports in other editions of the Holy Quran.

object? Ayah(int ayah, string edition = "")
object? Ayah(int surah, int ayah, string edition = "")

Parameters

• ayah: number of ayah
• surah: number of surah
• edition: an edition identifier. Example: en.asad for Muhammad Asad’s english translation.
• offset: offset ayahs in a juz by the given number.
• limit: number of ayahs that the response will be limited to.

Cases

Ayah(int ayah, string edition = "")

Returns an object (castable to Ayah object) of the Ayah with number ayah, edition edition.

Ayah(int ayah)

Returns an object (castable to ayah object) of ayah with number ayah and edition quran-simple

object? Ayah(int surah, int ayah, string edition = "")

Returns an object (castable to IEnumerable<Surah> object) of all Surahs of the holy Quran

Required Parameters

• ayah: number of ayah
• surah: number of surah

Example

var e1 = AlQuranV1.Ayah(262) as Ayah; // Returns Muhammad Asad's translation Ayat Al Kursi
var e2 = AlQuranV1.Ayah(2, 255) as Ayah; // Returns Muhammad Asad's translation Ayat Al Kursi
var e3 = AlQuranV1.Ayah(262, "ar.alafasy") as Ayah; // Returns Mishary Alafasy's recitation of the Ayat Al Kursi
var e4 = AlQuranV1.Ayah(262, "quran-uthmani,en.asad,en.pickthall") as IEnumerable<Ayah>; // Returns Ayat Al Kursi from 3 editions: Simple Quran, Muhammad Asad and Maramduke Pickthall

Return Value

object?

Note

Since the ayah API may return a single Surah, as in example e2 as well it might returns a list of Ayahs, as in examples e1, e4, it return an object type which can be safely casted to whichever type.

Search

Search the Holy Quran. Please note that only text editions of the Quran are searchable.

SearchResult? Search(string keyword, string editionOrLanguage, int surah)

Parameters

• keyword the keyword to seach for
• surah number of surah
• editionOrLanguage an edition identifier. Example: en.asad for Muhammad Asad’s english translation. or an language identifier. Example: en for english, ar for Arabic

Cases

SearchResult? Search(string keyword, string editionOrLanguage, int surah)

Returns and object of SearchResult with results of searching in edition[or, editions of the language] editionOrLanguage, only in Surah with number surah

SearchResult? Search(string keyword, string editionOrLanguage)

Returns and object of SearchResult with results of searching in edition[or, editions of the language] editionOrLanguage

Required Parameters

• keyword: the keyword to seach for
• editionOrLanguage: an edition identifier. Example: en.asad for Muhammad Asad’s english translation. or an language identifier. Example: en for english, ar for Arabic

Example

var e1 = AlQuranV1.Search("Abraham", "en"); //  Returns all ayahs that contain the word 'Abraham' in all the english editions
var e2 = AlQuranV1.Search("Abraham", "en.pickthall"); // Returns all ayahs that contain the word 'Abraham' in Maramduke Pickthall's English translation
var e3 = AlQuranV1.Search("Abraham", "en.pickthall", 37); // Returns all ayahs that contain the word 'Abraham' Surat As-Saafaat in Maramduke Pickthall's English translation

Return Value

SearchResult?

Manzil

The Quran has 7 Manzils (for those who want to read / recite it over one week). You can get the text for each Manzil using this method.

Manzil? Manzil(int manzil, string edition, int offset = -99, int limit = -99)

Parameters

• manzil: number of manzil.
• edition: an edition identifier. Example: en.asad for Muhammad Asad’s english translation.
• offset: offset ayahs in a juz by the given number.
• limit: number of ayahs that the response will be limited to.

Cases

Manzil? Manzil(int manzil, string edition)

Returns an object of manzil from edition edition of the Holy Quran

Manzil? Manzil(int manzil, string edition, int offset, int limit)

Required Parameters

• manzil: number of manzil

Example

var e1 = AlQuranV1.Manzil(7, "en.asad "); // Returns manzil 7 from Muhammad Asad's translation of the Holy Quran
var e2 = AlQuranV1.Manzil(7, "quran-uthmani"); // Returns the text of Manzil 7 of the Holy Quran
var e3 = AlQuranV1.Manzil(7, "quran-uthmani", 3, 10); // Returns the the ayahs 4-13 from Manzil 7

Return Values

An object of type manzil

Ruku

The Quran has 556 Rukus. You can get the text for each Ruku using the method below.

Ruku? Ruku(int ruku, string edition, int offset = -99, int limit = -99)

Parameters

• ruku: number of ruku.
• edition: an edition identifier. Example: en.asad for Muhammad Asad’s english translation.
• offset: offset ayahs in a juz by the given number.
• limit: number of ayahs that the response will be limited to.

Cases

Ruku? Ruku(int ruku, string edition)

Returns an object of Ruku from edition edition of the Holy Quran

Ruku? Ruku(int manzil, string edition, int offset, int limit)

Required Parameters

• ruku: number of manzil

Example

var e1 = AlQuranV1.Ruku(7, "en.asad"); // Returns ruku 7 from Muhammad Asad's translation of the Holy Quran
var e2 = AlQuranV1.Ruku(7, "quran-uthmani"); // Returns the text of ruku 7 of the Holy Quran
var e3 = AlQuranV1.Ruku(7, "quran-uthmani", 3, 3); // Returns the the ayahs 4-6 from ruku 7

Return Values

An object of type Ruku

Page

The Quran is traditionally printed / written on 604 pages. You can get the text for each page using the method below.

Page? Page(int page, string edition, int offset = -99, int limit = -99)

Parameters

• page: number of page.
• edition: an edition identifier. Example: en.asad for Muhammad Asad’s english translation.
• offset: offset ayahs in a juz by the given number.
• limit: number of ayahs that the response will be limited to.

Cases

Page? Page(int page, string edition)

Returns an object of Page from edition edition of the Holy Quran

Page? Page(int page, string edition, int offset, int limit)

Required Parameters

• page: number of page

Example

var e1 = AlQuranV1.Page(1, "en.asad "); // Returns page 1 from Muhammad Asad's translation of the Holy Quran
var e2 = AlQuranV1.Page(1, "quran-uthmani"); // Returns the text of page 1 of the Holy Quran
var e3 = AlQuranV1.Page(1, "quran-uthmani", 2, 2); // Returns the the ayahs 3-4 from page 1

Return Values

An object of type Page

Hizb

The Quran comprises 240 Hizb Quarters. One Hizb is half a Juz.

Hizb? Hizb(int hizb, string edition, int offset = -99, int limit = -99)

Parameters

• hizb: number of hizb.
• edition: an edition identifier. Example: en.asad for Muhammad Asad’s english translation.
• offset: offset ayahs in a juz by the given number.
• limit: number of ayahs that the response will be limited to.

Cases

Hizb? Hizb(int hizb, string edition)

Returns an object of Hizb from edition edition of the Holy Quran

Hizb? Ruku(int hizv, string edition, int offset, int limit)

Required Parameters

• hizb: number of hizb

Example

var e1 = AlQuranV1.Hizb(7, "en.asad "); // Returns hizb quarter 1 from Muhammad Asad's translation of the Holy Quran
var e2 = AlQuranV1.Hizb(7, "quran-uthmani"); // Returns the text of hizb quarater 1 of the Holy Quran
var e3 = AlQuranV1.Hizb(7, "quran-uthmani", 2, 2); // Returns the the ayahs 3-4 from hizb Quarter 1

Return Values

An object of type Hizb

Sajda

Depending on the madhab, there can be 14, 15 or 16 sajdas. This API has 15.

(IEnumerable<Ayah>, Edition) Sajda(string edition)

Parameters

• edition: an edition identifier. Example: en.asad for Muhammad Asad’s english translation.

Cases

(IEnumerable<Ayah>, Edition) Sajda(string edition)

Returns a tuple of IEnumerable<Ayah> and Edition contains Sajdas of the edition and metadata about the edition, respectively.

(IEnumerable<Ayah>, Edition) Sajda()

Returns a tuple of IEnumerable<Ayah> and Edition contains Sajdas of the edition and metadata about the quran-simple edition.

Required Parameters

None.

Example

var e1 = AlQuranV1.Sajda("en.asad "); // Returns the text of sajda ayahs of the Holy Quran

Return Values

An object of type (IEnumerable<Ayah>, Edition)

Improve Documentation

Refactor Classes to Be non-static, to facilitate .NET management

Add Unit Testing Class

Note About Meta

I did not implement an interface for the meta API (http://api.alquran.cloud/v1/meta), and I’m not sure of adding ‘yet’, because of: 1. It seems useless since all the metadata can be concatenated throw the AlquranV1 methods, using an extention method for example. 2. It is too complex type to bind.