https://github.com/islamic-network/alquran-apidotnet-client

An AlQuran DotNet API Client
https://github.com/islamic-network/alquran-apidotnet-client
Last synced: about 1 year ago
JSON representation
An AlQuran DotNet API Client
Host: GitHub
URL: https://github.com/islamic-network/alquran-apidotnet-client
Owner: islamic-network
License: gpl-3.0
Created: 2022-06-08T20:25:12.000Z (about 4 years ago)
Default Branch: master
Last Pushed: 2022-06-28T13:46:47.000Z (about 4 years ago)
Last Synced: 2023-04-29T21:55:24.304Z (about 3 years ago)
Language: C#
Homepage: https://www.nuget.org/packages/alquran/
Size: 54.7 KB
Stars: 5
Watchers: 1
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.org
Awesome Lists containing this project

README

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

* Contents :TOC_3:

  - [[#alquran][Alquran]]

  - [[#demo][Demo]]

  - [[#usage][Usage]]

    - [[#edition][~Edition~]]

    - [[#quran][~Quran~]]

    - [[#juz][~Juz~]]

    - [[#surah][~Surah~]]

    - [[#ayah][~Ayah~]]

    - [[#search][~Search~]]

    - [[#manzil][~Manzil~]]

    - [[#ruku][~Ruku~]]

    - [[#page][~Page~]]

    - [[#hizb][~Hizb~]]

    - [[#sajda][~Sajda~]]

  - [[#improve-documentation][Improve Documentation]]

  - [[#refactor-classes-to-be-non-static-to-facilitate-net-management][Refactor Classes to Be non-static, to facilitate .NET management]]

  - [[#add-unit-testing-class][Add Unit Testing Class]]

  - [[#note-about-meta][Note About ~Meta~]]

** Alquran

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

- Dependencies:

  - [[https://www.nuget.org/packages/RestSharp/][RestSharp]] (>= 107.3.0)

  - [[https://www.nuget.org/packages/RestSharp.Serializers.NewtonsoftJson/][RestSharp.Serializers.NewtonsoftJson]] (>= 107.3.0)

This release was built using .NET 6

** Demo

#+begin_src csharp

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

#+end_src

** 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.

#+begin_src csharp

IEnumerable? Editions(string format, string lang, string type)

#+end_src

**** 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:

#+begin_src csharp

IEnumerable? Editions(string lang)

#+end_src

Lists all editions for a given format:

#+begin_src csharp

IEnumerable? Editions(string format)

#+end_src

Lists all editions for a given type:

#+begin_src csharp

IEnumerable? Editions(string type)

#+end_src

**** Required Parameters

None

**** Default Values

Returns a list of all available editions

**** Example

#+begin_src csharp

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

#+end_src

**** Return Type

This methods always returns an ~IEnumerable~

*** ~Quran~

Returns a complete Quran edition in the audio or text format

#+begin_src csharp

Quran? Quran(string edition)

#+end_src

**** Parameters

+ ~edition~: an edition identifier. Example: en.asad for Muhammad Asad's english translation

**** Cases

#+begin_src csharp

Quran? Quran()

#+end_src

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

#+begin_src csharp

Quran? Quran(string edition)

#+end_src

Returns a complete Quran edition.

**** Default Values

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

**** Required Parameters

None

**** Example

#+begin_src csharp

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

#+end_src

**** 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.

#+begin_src csharp

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

#+end_src

**** 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

#+begin_src csharp

Juz? Juz(int juz, string edition)

#+end_src

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

#+begin_src csharp

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

#+end_src

**** Required Parameters

+ ~juz~: number of juz

**** Example

#+begin_src csharp

var e1 = AlQuranV1.Juz(30, "en.asad");

var e2 = AlQuranV1.Juz(30, "quran-uthmani");

var e3 = AlQuranV1.Juz(1, "quran-uthmani", 3, 10);

#+end_src

**** 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.

#+begin_src csharp

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

#+end_src

**** 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

#+begin_src csharp

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

#+end_src

Returns an object (castable to ~Surah~ object) of the Surah with number ~surah~, edition

~edition~ and offset ~offset~ to the limit ~limit~.

#+begin_src csharp

object? Surah(int surah)

#+end_src

Returns an object (castable to ~Surah~ object) of Surah with number ~surah~ and edition

~quran-simple~. It will return an object castable to ~IEnumerable~ if ~edition~ is

more than 1 edition.

#+begin_src csharp

object? Surah()

#+end_src

Returns an object (castable to ~IEnumerable~ object) of all Surahs of the holy Quran

**** Default Value

Returns an object (castable to ~IEnumerable~ object) of all Surahs of the holy Quran

**** Required Parameters

None

**** Example

#+begin_src csharp

var e1 = AlQuranV1.Surah() as IEnumerable; // 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; //  Returns Surat An-Naas from 3 editions: Simple Quran, Muhammad Asad and Marmaduke Pickthall

#+end_src

**** 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.

#+begin_src csharp

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

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

#+end_src

**** 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

#+begin_src csharp

Ayah(int ayah, string edition = "")

#+end_src

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

~edition~.

#+begin_src csharp

Ayah(int ayah)

#+end_src

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

#+begin_src csharp

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

#+end_src

Returns an object (castable to ~IEnumerable~ object) of all Surahs of the holy Quran

**** Required Parameters

+ ~ayah~: number of ayah

+ ~surah~: number of surah

**** Example

#+begin_src csharp

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; // Returns Ayat Al Kursi from 3 editions: Simple Quran, Muhammad Asad and Maramduke Pickthall

#+end_src

**** 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.

#+begin_src csharp

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

#+end_src

**** 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

#+begin_src csharp

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

#+end_src

Returns and object of ~SearchResult~ with results of searching in edition[or, editions of

the language] ~editionOrLanguage~, only in Surah with number ~surah~

#+begin_src csharp

SearchResult? Search(string keyword, string editionOrLanguage)

#+end_src

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

#+begin_src csharp

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

#+end_src

**** 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.

#+begin_src csharp

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

#+end_src

**** 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

#+begin_src csharp

Manzil? Manzil(int manzil, string edition)

#+end_src

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

#+begin_src csharp

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

#+end_src

**** Required Parameters

+ ~manzil~: number of manzil

**** Example

#+begin_src csharp

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

#+end_src

**** 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.

#+begin_src csharp

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

#+end_src

**** 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

#+begin_src csharp

Ruku? Ruku(int ruku, string edition)

#+end_src

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

#+begin_src csharp

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

#+end_src

**** Required Parameters

+ ~ruku~: number of manzil

**** Example

#+begin_src csharp

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

#+end_src

**** 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.

#+begin_src csharp

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

#+end_src

**** 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

#+begin_src csharp

Page? Page(int page, string edition)

#+end_src

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

#+begin_src csharp

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

#+end_src

**** Required Parameters

+ ~page~: number of page

**** Example

#+begin_src csharp

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

#+end_src

**** Return Values

An object of type ~Page~

*** ~Hizb~

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

#+begin_src csharp

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

#+end_src

**** 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

#+begin_src csharp

Hizb? Hizb(int hizb, string edition)

#+end_src

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

#+begin_src csharp

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

#+end_src

**** Required Parameters

+ ~hizb~: number of hizb

**** Example

#+begin_src csharp

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

#+end_src

**** Return Values

An object of type ~Hizb~

*** ~Sajda~

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

#+begin_src csharp

(IEnumerable, Edition) Sajda(string edition)

#+end_src

**** Parameters

+ ~edition~: an edition identifier. Example: en.asad for Muhammad Asad's english translation.

**** Cases

#+begin_src csharp

(IEnumerable, Edition) Sajda(string edition)

#+end_src

Returns a tuple of ~IEnumerable~ and ~Edition~ contains Sajdas of the edition and

metadata about the edition, respectively.

#+begin_src csharp

(IEnumerable, Edition) Sajda()

#+end_src

Returns a tuple of ~IEnumerable~ and ~Edition~ contains Sajdas of the edition and

metadata about the quran-simple edition.

**** Required Parameters

None.

**** Example

#+begin_src csharp

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

#+end_src

**** Return Values

An object of type ~(IEnumerable, Edition)~

** TODO Improve Documentation

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

** TODO 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.
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/islamic-network/alquran-apidotnet-client

Awesome Lists containing this project

README
