fawazahmed0 / hadith-api

Free Hadith API Service with Multiple Languages and Multiple Grades

Hadith API

In the name of God, who has guided me to do this work

Features:

• Free & Blazing Fast response
• No Rate limits
• Multiple Languages
• Multiple Grades

URL Structure:

https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@{apiVersion}/{endpoint}

Formats:

The Endpoints Supports HTTP GET Method and returns the data in two formats:

/{endpoint}.json

/{endpoint}.min.json

The above formats also work for fallback i.e if .min.json link fails, you can use .json link and vice versa

Warning: You should include fallback mechanism in your code, to avoid issues

Endpoints:

• /editions
  

Lists all the available editions in prettified json format:
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions.json

Get a minified version of it:
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions.min.json

• /editions/{editionName}
  

Get the whole hadith/hadith translation:
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-abudawud.json

• /editions/{editionName}/{HadithNo}
  

Get the 1035th Hadith:
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-abudawud/1035.json

Get the 1035th Hadith in minified format:
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-abudawud/1035.min.json

• /editions/{editionName}/sections/{sectionNo}
  

Get Section 7:
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-abudawud/sections/7.json

• /info
  

Get all the details about hadith book, such as hadith grades, books reference etc
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/info.json

Contribution:

Without your contribution, this work won't survive, whenever you find any issue, please let me Know, so that I can also fix it and people can benefit from it, incase of any question, issue or problems etc
you can let me Know

• Please help by adding new translations to this repo, you can share me the translation here

or

• Read Contribute to add/update the translation directly to this repo

Download: Here

Any Issues: Raise here

Demos:

Projects using Hadith API:

• Hadiths
• Quran Hadith Search Engine

Other Similar Projects:

• Quran-api

Share:

Please share this with your friends and Star this repo by clicking on ⭐ button above ↗️

References:

All the open source projects and dawah/Islamic organizations

Please see References

✏️Improve this page

hadith-api's Issues

Different number of hadiths in Urdu versions

When I print the length of the hadiths array, it contains different number of hadiths for the Urdu version.

print(len(data['ara']['hadiths']))
print(len(data['ara1']['hadiths']))
print(len(data['eng']['hadiths']))
print(len(data['urd']['hadiths']))

would result in

7589
7589
7589
7586

for bukhari shareef.

Why is there a discrepancy, and how can this be resolved?
I'm parsing the main json files:

Thanks.

Change Munqar to Munkar

#24

Data sources

Hello brother, I hope you are doing well.

I crawled data from two sources:

• sunnah.com
• dorar.net

And the data is provided here.

I hope that you can use the data and improve your work based on it.
The data has no documentation until now, if you have any questions please contact me on:

• email: [email protected]
• telegram: @aliosm97

Thanks for your great work, keep it up!

Remove Section 0 in "sections" and "section_details"

Asselamu Aleykum,
Maybe removing Section 0 except in "Sahih Muslim" and "Sunan ibn Majah" is a good idea because there is no need for that.

For example in "Jami at Tirmidhi" its even more confusing because "sections" starts with 0 while "section_details" starts with 1

Refer other hadith apis and websites to make this api better

sunnah api & website, hadithenc etc

Also see all PR's & issues ( closed & open)
Also refer sunnah.com github (& other hadith apis) issues

Need to add missing things (like sections names, subsection names etc)

should include arabic metadata? if arabic, then also need to consider metadata for other languages like bangla,urdu etc(json structure should be easily able to add metadata for other languages)

Prioritize issues

Translation error in Zubair Ali Zai grading.

https://github.com/fawazahmed0/hadith-api/blob/1/editions/eng-tirmidhi/3377.json
it says

Son Mountain Pleased Allah With him Of the Say Of Sanaad Disconnected Sheikh Mercy Allah By Told Extra Son My father Extra Son did not Son Mountain Pleased Allah With him And See Research Articles (4/ 566)

https://zubairalizai.com/tirmizi/3377/

معاذ بن جبل رضی اللہ عنہ کے قول کی سند منقطع ہے، شیخ رحمہ اللہ نے فرمایا: ’’زیاد بن أبي زیاد مولی ابن عیاش لم یدرک معاذ بن جبل رضي اللّٰہ عنہ‘‘، وانظر تحقیقی مقالات (4/ 566)

2 options - either to remove the grading in this hadith or to put a better translation which I am writing below.

The chain of Muadh ibn Jabal (رضی اللہ عنہ)'s narration is disconnected. Sheikh (Zubair) رحمہ اللہ said, "Ziyad bin Abi Ziyad, the freed slave of Ibn Ayyash did not meet Muadh ibn Jabal (رضی اللہ عنہ)". See Research Articles (4/ 566)

I personally think it should be removed since it is too big.

Parsing issue in infofixer

Asselamu Aleykum,

I am trying to add 3604j (3604.10) to the info.json file. However, I am unable to add 3604.10 as it gets automatically replaced with 3604.1 after running the infofixer. This is most likely due to the fact that in the context of math, 3604.1 and 3604.10 are equivalent.

Is there any way to resolve this issue without converting the float to a string?

Silsila as sahih

https://al-hadees.com/hadees-name/silsila-sahih/0

Section 0

Why there is section 0? It is confusing me with my code, some books dosent got it but some got
what is it?

Grading issue in zubair ali zai

Asselamu aleykum,
Sometimes the hadith grade text differs from the original text. But maybe this is intended?
Example:
https://zubairalizai.com/nasai/#1305 says "Hadith Hasan" while
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-nasai/1304.json says "Hadith Hasan or Sahih"
(There is a minor difference in numeration but its actually the same hadith)

Is there any reason for this? The statement is correct because the Hadith is actually hasan but people could misinterpret "Hasan or Sahih" as the words of Sheikh Zubair even if he only said "hasan".

Add Sheikh Zubair Ali Zai description

As-salamu alaykum,

I have published my own script for scraping zubairalizai.com, and the correctly scraped files (including Sheikh Zubair Ali Zai's gradings and explanations) can be found in my repository.

It may be helpful to add a JSON object with Sheikh Zubair Ali Zai's explanations to the scraped data. Sometimes, he classifies a hadith as da'if (weak) but explicitly states in the "description" that the hadith before is establishing this hadith, as in this example.

If we were to include the grade in one JSON object and the description in another, we could display the simple grading with an info button next to it. If someone clicks on the info button, they would be able to see why Sheikh Zubair Ali Zai graded the isnad as da'if and any additional information if the meaning of this hadith is still correct.

I am mentioning this idea now because you are already thinking about structure changes and this would be an improvement we should discuss as well.

better translations (add later at last)

turkusk :http://www.normalift.com/kitap/files/mus/had/003/0261.htm

https://github.com/alQuranBD/Bangla-Hadith-api

How hadith reference work?

Assalaamualikum brother,
I need all the books in a database, i'm converting all this json into a RDBMS but i have a little confusion..

///////////////////
"reference": {
"book": 4,
"hadith": 1
}
////////////////
Can you explain this bit, how does this work, i mean what is this book number and hadith number does it refers to the book of the same number and like wise hadith if so then book number shouldn't exceed 6, or in this case 7, but it does.
Please correct me!
Thank you!

apiscript.js removes the ending punctuations.

Noticed that the database/line-by-line is missing all the ending punctuations in English translation (Didn't check them in others). I manually added them in one file (eng-malik) and regenerated the data using apiscript update command.

The manually added punctuation was removed when the updated file was created in line-by-line folder.

Add hadith in germany

https://islamische-datenbank.de/

file.zip

See other websites , apps as well, might find better source

Note: Not adding bukhari & muslim in germany from here, as the number of hadiths are few in numbers

Add hadith gradings by Imam Tirmidhi.

Imam Tirmidhi mentions the gradings of the hadith in the Arabic text after the hadith text.

This data could be parsed to get the hadith gradings.

For example - https://www.hadithhub.com/tirmidhi:684

قَالَ أَبُو عِيسَى حَدِيثُ أَبِي هُرَيْرَةَ حَدِيثٌ حَسَنٌ صَحِيحٌ
Abu Isa (Imam Tirmidhi) said that the hadith of Abu Hurayrah is Hasan Sahih.

Issue regarding using fonts for uthmanic-hafs1-ver14.ttf

I am attempting to use the uthmanic-hafs1-ver14.ttf font with the ara-quranuthmanihaf.json data for the Quran.

However, there doesn't seem to be some characters that are formatting to the proper font correctly. Please see my example below.

The arrows point to unicode characters that don't follow the proper font style. Am I using the incorrect font? Is there another json file I should be using instead when using the hafs Quran?

JZK.

Add first and last hadith number of every section

Asselamu Aleykum,
An example can be found here: https://sunnah.com/tirmidhi

The Book on Purification
firsthadith 1
lasthadith 148

The Book on Salat
firsthadith 149
lasthadith 451
etc...

This makes the navigation more simple, because its possible to display the range of ahadith number in a section to the user

Translation names (not a issue)

Assalamualaikum!

Can you please add a file in repo for the available languages the API is available in?

Jazak Allah

sunan Abu dawood book 1 hadith number 64 65

missing hadiths sunan Abu dawood book 1 hadith number 64 65

Possible issue in gradings by Bashar Awaad Marouf in Jami At Tirmidhi

Assalamualekum.

Grading source for Tirmidhi:2 - https://fawazahmed0.github.io/maktaba-grades-backup/33861/6#p1
Marked as hasan sahih by Bashar Awaad Marouf. (https://www.hadithhub.com/tirmidhi:2)

But in the text I find "هَذَا حَدِيثٌ حَسَنٌ صَحِيحٌ , وَهُوَ حَدِيثُ مَالِكٍ، عَنْ سُهَيْلٍ، عَنْ أَبِيهِ، عَنْ أَبِي هُرَيْرَةَ." which is the wordings of Imam Tirmidhi (check the Arabic text in hadithhub which makes it very clear.) and not Bashar Awaad Marouf. I could not find the gradings of Dr Bashar for that hadith in alMaktaba backup.

create csv files

For both quran
and
hadith (languages, grades in column)

Specifically for wordpress etc

edition.json to csv

Update:
csv link

random hadith endpoint

Salaam, is there any way we can get a random hadith using this API and Python? Any code sample?

Include fallback mechanism in your code to avoid issues

This API have multiple fallback urls:

Fallback URL:

https://raw.githubusercontent.com/fawazahmed0/hadith-api/{apiVersion}/{endpoint}

Pseudo code:
For example, if you want to fetch eng-muslim edition

Fetch https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-muslim.min.json
If above url fails, then try fetching https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-muslim.json
If above url fails, then try fetching https://raw.githubusercontent.com/fawazahmed0/hadith-api/1/editions/eng-muslim.min.json
If above url fails, then try fetching https://raw.githubusercontent.com/fawazahmed0/hadith-api/1/editions/eng-muslim.json

Developed www.islam.quest using data provided by you :)

Hi Fawaz, I developed this website islam.quest which is an extremely fast hadith and quran search engine built using the data provided by you, kindly take a look at it and leave your feedback here, I just wanted to say thank you so much for your hard-work, keep it up.

clean up bangla translations

https://fawazahmed0.github.io/hadiths/books/bukhari/4635

Either extract data from app or any bangla hadith api on github

Wrong in-book reference in Muwatta Malik

Asselamu Aleykum,
The "in-book reference" in Muwatta Malik is everywhere the "hadithnumber". Example:
"hadiths": [ { "hadithnumber": 1020, "arabicnumber": 1020, "text": "Yahya related to me ....", "grades": [ { "name": "Salim al-Hilali", "grade": "Sahih" } ], "reference": { "book": 22, "hadith": 1020 } } ]

Instead of "Book 22, Hadith 1020" it should be "Book 22, Hadith 8"

Add sources/reference list

Found a few trunctated hadith.

https://raw.githubusercontent.com/fawazahmed0/hadith-api/1/editions/eng-nasai/4255.json

It was narrated that Khalid said:"Al-Miqdam bi

https://sunnah.com/nasai:4255

It was narrated that Khalid said:
"Al-Miqdam bi8n Ma di Karib came to visit Mu awiyah and said to him: I adjure you by Allah, do you know that the messenger of Allah forbade wearing the Hides of predators and riding on them? He said: 'yes."

Add chapter names within the books.

For example - https://sunnah.com/tirmidhi/1

You can see various chapter names like

(1) Chapter: What Has Been Related That Salat Is Not Accepted Without Purification
(2) Chapter: What Has Been Related About The Virtue Of Purification

etc.

I can work on this but first need to finalize the json structure.

{
	"metadata": {
		"name": "Jami At Tirmidhi",
		"section": {
			"1": "The Book on Purification"
		},

	},
	"hadiths": [
		{
			"hadithnumber": 1,
			"arabicnumber": 1,
			"text": ".........................",
			"grades":[....................],
			"reference": {
				"book": 1,
				"hadith": 1
			}
		}
	]
}

I recommend adding a sub json within the "hadiths" json

"chapter": {
    "id": 1,
    "isFirstHadithOfChapter": true,
    "eng-name": "Chapter: What Has Been Related That Salat Is Not Accepted Without Purification",
    "ara-name": " باب مَا جَاءَ لاَ تُقْبَلُ صَلاَةٌ بِغَيْرِ طُهُورٍ ‏ "
    }

The effective json will look like :

{
	"metadata": {
		"name": "Jami At Tirmidhi",
		"section": {
			"1": "The Book on Purification"
		},

	},
	"hadiths": [
		{
			"hadithnumber": 1,
			"arabicnumber": 1,
                        "chapter": {
                                "id": 1,
                                "isFirstHadithOfChapter": true,
                                "eng-name": "Chapter: What Has Been Related That Salat Is Not Accepted Without Purification",
                                "ara-name": " باب مَا جَاءَ لاَ تُقْبَلُ صَلاَةٌ بِغَيْرِ طُهُورٍ ‏ "
                        }
			"text": ".........................",
			"grades":[....................],
			"reference": {
				"book": 1,
				"hadith": 1
			}
		}
	]
}

Let me know if you are ok with this design. I can start working on this.

Musnad Ahmad with gradings

After jami kamil is released, so these things can be done together

Incomplete hadith text in Google Sheet cell.

AoA,

Is there any limitation that a certain number of characters can be accessed when JSON is fetched in Google Sheets. I am getting incomplete hadith text. Any idea how to get full hadith text?

"same chain of narrators" and empty hadiths

Salam

When we access the Hadith ENDPOINT for Sahih Muslim, we get many hadiths which are simply statements like

A hadith like this has been narrated on the authority of Abu Huraira (Allah be pleased with him) through another chain of transmitters and we also get empty hadiths etc. is there any list of the hadith numbers that contain such things which aren't actual hadiths, so that we may block them out when we access the API? Or any other workaround that you could suggest?

Regards

Get translations from apps

extract sqlite db

french, malayalam, hindi, german, roman urdu etc

Search more

Further partition the text of hadith

Further partition the text of hadith.

Have a look at this - https://us-west1-hadeeth.cloudfunctions.net/hadith/bukhari/2

This api has further partitioned the text of the Hadith as Prefix (containing the chain of narrations), Post-fix (Comment by the narrator).

This would help in better parsing of data.

Translation and grading discrepancy in Sunan Nasai.

https://sunnah.com/nasai:352 and https://sunnah.com/nasai:353 are same.

but hadith-api has different grading for both.

https://github.com/fawazahmed0/hadith-api/blob/1/editions/ara-nasai/352.json (Al-Albani : Sahih)

https://github.com/fawazahmed0/hadith-api/blob/1/editions/ara-nasai/353.json (Al-Albani : Daif)

Add Bosnian translation

Here are the official Bosnian translations of the Ahadith.

Sahih Bukhari Bosnian:
https://archive.org/details/BuharijevaZbirkaHadisa/

Sahih Muslim Bosnian:
https://archive.org/details/MuslimovaZbirkaHadisa/

An-Nasa'i Bosnian:
https://archive.org/details/SunenNesai/

Abu Dawud Bosnian:
https://archive.org/details/sunenEbuDavuda/

At-Tirmidhi Bosnian:
https://archive.org/details/tirmizijnaZbirkaHadisa/

Ibn Majah (Not Available)

Muwatta Bosnian:
https://archive.org/details/bs_Muv

apiscript needs to be fixed for ahadith which contain multiple narration

Asselamu Aleykum,
Two Issues

Issue 1:
Example:
1.
Turkish Tirmidhi 3604
You can only see "3604"
3604.1, 3604.2 etc are missing completely instead of mentioning them with an empty text like here:
English Muslim 2
2.
You can only see "3604, 3604.2, 3604.3 3604.4, 3604.5, 3604.6, 3604.7, 3604.8, 3604.9, 3604.10" if text isn't empty like here.
English Tirmidhi 3604

This is only one example from many ones. All ahadith which don't have any translation should be shown with an empty text. For "Integers" this works perfectly fine but as soon as you try it with an "Double" Hadithnumber like 3604.2, 3604.3 etc it is missing completely instead of an empty text.

Especially for me this is important because I am iterating through the Arabic and Translated json file. So if the 3605th position of the arabic file is "Hadith 1604.2" while the 3605th position of the Turkish file is "Hadith 3605", this would lead to wrong results.

Issue 2:
All "Double" Hadithnumbers like "3604.1, 3604.2" etc are always shown as "book 0, chapter 0" :
English Tirmidhi 3604
instead of

"book": 48,
"hadith": 236

and so on....

read files

I can't read files
thanks to help me

Unique Integer System for Hadith Numbering

Asselamu Aleykum,
What's the point of "hadithnumber" if it's identical to "arabicnumber" everywhere except in "Sahih Muslim"? Perhaps making "hadithnumber" a unique integer number, like a "primary key" would make more sense. That way, every hadith can be attributed to a unique integer number.

Current situation in Sahih Bukhari (also in other books):

		{
			"hadithnumber": 402,
			"arabicnumber": 402,
			"text": "",
			"grades": [],
			"reference": {
				"book": 8,
				"hadith": 53
			}
		},
		{
			"hadithnumber": 402.2,
			"arabicnumber": 402.2,
			"text": "",
			"grades": [],
			"reference": {
				"book": 8,
				"hadith": 54
			}
		},
		{
			"hadithnumber": 403,
			"arabicnumber": 403,
			"text": "",
			"grades": [],
			"reference": {
				"book": 8,
				"hadith": 55
			}
		},

My suggestion in Sahih Bukhari (also in other books):

		{
			"hadithnumber": 402,
			"arabicnumber": 402,
			"text": "",
			"grades": [],
			"reference": {
				"book": 8,
				"hadith": 53
			}
		},
		{
			"hadithnumber": 403,
			"arabicnumber": 402.2,
			"text": "",
			"grades": [],
			"reference": {
				"book": 8,
				"hadith": 54
			}
		},
		{
			"hadithnumber": 404,
			"arabicnumber": 403,
			"text": "",
			"grades": [],
			"reference": {
				"book": 8,
				"hadith": 55
			}
		},

Adding source of the gradings.

I got a feedback on the website hadithhub.com "How can I trust the grades?".

Would it be possible to add the source from where the grades have been parsed?

Question about the quality

First of all thanks for this work!

I want to build on top of your data, so can I trust the data quality?
It will be helpful if you can mention the data sources.

Best,
Ali Fadel

Referencing issue in malik muwatta

Asselamu Aleykum,
Which site is used as reference for "Muwatta Malik" ?

For example:
https://fawazahmed0.github.io/hadiths/books/malik/957

The english one is showing a statement of Imam Malik before the Hadith while the Arabic text only shows the hadith. And the book reference also seems to be odd.

The statement of Imam Malik which can be found in English in 957 can be found in Urdu in 956.5
https://fawazahmed0.github.io/hadiths/books/malik/956

In Sunnah.com the statement of Imam Malik and the hadith are shown as two separate ahadith:
https://sunnah.com/malik/20 (Book 20 Hadith 263/264)

So I am not sure. Should the statement of Imam Malik be a separate hadithnumber ? Should it be connected to 956 just like the urdu text? Or should it be shown before 957 at the beginning just like the english text? Or should we completely remove the statement of Imam Malik just like the arabic text ?

It would be nice to have a reference in this matter.

Add Muslim & bukhari gradings [Low prority]

https://islamqa.info/en/answers/119516/are-there-any-daeef-weak-hadiths-in-al-bukhaari-and-muslim
https://www.google.com/search?client=firefox-b-d&q=does+sahih+muslim+have+daif+hadith

Standardized references for Kutub al-Sittah

Asselamu Aleykum,
There should be a standardized reference for ahadith. For now some references are adopted by sunnah.com while others are adopted by urdu sites, darussalam etc.. We should stick to one principle.

Example:
Urdu sites and the official darussalam book is showing this hadith in "Sunan An-Nasai 208":
https://hamariweb.com/islam/hadith/sunan-an-nasai-208/
https://kalamullah.com/Books/Hadith/Sunan%20an-Nasai%20Vol.%201%20-%201-876.pdf

While Sunnah.com and this api shows the hadith "209" in "Sunan An-Nasai 208" and completely skips "208":
https://sunnah.com/nasai:208
https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-nasai/208.json

I can fix it, that's not the problem but I need to know which standard we are referring to.
My suggestion would be lets use the reference given by darussalam and Hafidh Zubair Ali Zai because sunnah.com skips some Ahadith:
https://kalamullah.com/sahih-bukhari.html
https://kalamullah.com/sahih-muslim.html
https://kalamullah.com/sunan-an-nasai.html
https://kalamullah.com/jami-at-tirmidhi.html
https://kalamullah.com/sunan-abu-dawood.html
https://kalamullah.com/ibn-majah.html

Some Hadith are missing

For eg - Bukhari 4434 is missing in linebyline folder.

Also missing in API - https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions/eng-bukhari/4434.min.json

But Sunnah.com has it - https://sunnah.com/bukhari:4434

There are multiple such issues

DepShield Deprecation Notice

Depshield will be deprecated on Monday December 12th

Please install our new product, Sonatype Lift with advanced features

Add new arabic versions without diacritics to allow searching

Do this in hadith api and quran api for arabic text with diacritics

This will help people who use arabic to search

For quran, do this for siraj tafseer and for hadith do for all arabic with diacritics

Grading issue in Al Albani - Sunan Nasai:36

https://github.com/fawazahmed0/hadith-api/blob/1/editions/eng-nasai/36.json

it says Al Albani graded it Daif.

But

https://shamela.ws/book/1147/18#p1

says it is Sahih.

[DepShield] (CVSS 7.5) Vulnerability due to usage of ssri:5.3.0

Vulnerabilities

DepShield reports that this application's usage of ssri:5.3.0 results in the following vulnerability(s):

• (CVSS 7.5) [CVE-2021-27290] ssri 5.2.2-8.0.0, fixed in 8.0.1, processes SRIs using a regular expression whic...

---

Occurrences

ssri:5.3.0 is a transitive dependency introduced by the following direct dependency(s):

• npm-registry-client:8.6.0
        └─ ssri:5.3.0

_{This is an automated GitHub Issue created by Sonatype DepShield. Details on managing GitHub Apps, including DepShield, are available for personal and organization accounts. Please submit questions or feedback about DepShield to the Sonatype DepShield Community.}