HadisYar API · نسخه 1.0

کلام معصومین را به اپ، ربات و سایت خود بیاورید

وب‌سرویس REST ساده و رایگان با ۲۱٬۹۳۵ حدیث، متن عربی با اعراب، ترجمه فارسی و منبع دقیق. بدون ثبت‌نام و بدون کلید؛ همین حالا امتحان کنید.

  • بدون کلید و ثبت‌ناممستقیم درخواست بفرستید.
  • CORS آزاداز مرورگر و فرانت‌اند هم کار می‌کند.
  • سریع و کش‌شدهپاسخ در چند میلی‌ثانیه.
  • خروجی متنی برای ربات‌هابا format=text

هزینهٔ استفاده: سه صلوات برای تعجیل در فرج مولا امام زمان علیه السلام - روحی فداه

کنسول زنده — درخواست را تغییر دهید و اجرا کنید

        

شروع سریع

نشانی پایه همه درخواست‌ها:

https://hadisyar.ir/api/v1

یک درخواست GET ساده کافی است؛ پاسخ JSON با کدگذاری UTF-8 است و متن فارسی و عربی بدون escape برمی‌گردد:

curl "https://hadisyar.ir/api/v1/hadis/day"
«حدیث روز» برای همه کاربران یکسان است و ساعت ۰۰:۰۰ به وقت تهران عوض می‌شود. تاریخ حدیث در هدر X-Hadis-Date برمی‌گردد.

اندپوینت‌ها

GET /api/v1/hadis/day حدیث روز

هر روز (به وقت تهران) یک حدیث کوتاه و یکسان برای همه کاربران. مناسب برای «حدیث روز» سایت، ربات و نمایشگر مسجد.

پارامترنوعتوضیح
date string تاریخ میلادی با قالب YYYY-MM-DD؛ پیش‌فرض: امروز
narrator integer حدیث روز فقط از یک گوینده خاص (مثلاً 10 برای امام رضا ع)
format string قالب خروجی: json یا text (متن آماده برای ربات‌ها و پیامک) — پیش‌فرض json
GET /api/v1/hadis/day
GET /api/v1/hadis/random حدیث تصادفی

در هر درخواست یک حدیث تصادفی؛ با امکان محدود کردن به گوینده، موضوع یا طول متن.

پارامترنوعتوضیح
narrator integer شناسه گوینده (۰ تا ۱۴) — فهرست در /narrators
subject string نام دقیق موضوع (از /subjects)
maxLength integer حداکثر تعداد نویسه ترجمه فارسی؛ برای کارت‌ها و استوری‌ها مفید است
format string قالب خروجی: json یا text (متن آماده برای ربات‌ها و پیامک) — پیش‌فرض json
GET /api/v1/hadis/random?narrator=8&maxLength=160
GET /api/v1/hadis/{id} دریافت یک حدیث

متن کامل عربی، ترجمه، گوینده و منبع یک حدیث با شناسه یکتا.

پارامترنوعتوضیح
id الزامی integer · path شناسه حدیث
format string قالب خروجی: json یا text (متن آماده برای ربات‌ها و پیامک) — پیش‌فرض json
GET /api/v1/hadis/500
GET /api/v1/hadis/batch دریافت گروهی

دریافت چند حدیث در یک درخواست (حداکثر 20 شناسه). نسخه POST با بدنه JSON مانند [12, 500, 9000] هم پشتیبانی می‌شود.

پارامترنوعتوضیح
ids الزامی string شناسه‌ها، جداشده با ویرگول
GET /api/v1/hadis/batch?ids=12,500,9000
GET /api/v1/narrators فهرست گویندگان

پیامبر اکرم (ص)، چهارده معصوم (ع) و احادیث قدسی، همراه با تعداد احادیث هر یک.

GET /api/v1/narrators
GET /api/v1/narrators/{id} یک گوینده

اطلاعات یک گوینده با شناسه.

پارامترنوعتوضیح
id الزامی integer · path شناسه گوینده (۰ تا ۱۴)
GET /api/v1/narrators/10
GET /api/v1/subjects موضوعات

موضوعات احادیث به ترتیب فراوانی؛ با پارامتر q برای تکمیل خودکار.

پارامترنوعتوضیح
q string بخشی از نام موضوع
limit integer حداکثر تعداد (۱ تا ۵۰۰) — پیش‌فرض 30
GET /api/v1/subjects?q=صبر&limit=5
GET /api/v1/sources منابع

کتاب‌های منبع به ترتیب تعداد حدیث.

پارامترنوعتوضیح
limit integer حداکثر تعداد (۱ تا ۵۰۰) — پیش‌فرض 30
GET /api/v1/sources?limit=5
GET /api/v1/stats آمار

شمار احادیث، گویندگان، موضوعات و منابع.

GET /api/v1/stats

ساختار داده

هر حدیث در همه اندپوینت‌ها همین شکل را دارد (نمونه: حدیث شماره ۵۰۰):

{
  "id": 500,
  "narrator": {
    "id": 2,
    "name": "امام علی (ع)",
    "slug": "imam-ali",
    "fullName": "امیر المؤمنین علی بن ابیطالب (علیه السلام)",
    "arabicTitle": "قال الإمام عليّ عليه السلام:",
    "persianTitle": "حضرت علی علیه السلام می فرمایند:"
  },
  "subject": "بدی و آثار آن",
  "arabic": "الشّرّ أقبح الأبواب",
  "arabicPlain": "الشر اقبح الابواب",
  "persian": "بدی، زشت ترین درهاست.",
  "source": {
    "book": "غرر الحکم و درر الکلم",
    "reference": "غرر الحکم و درر الکلم، ج 1، ص 135"
  },
  "url": "https://hadisyar.ir/hadis/500"
}
فیلدتوضیح
idشناسه یکتا و پایدار حدیث
narratorگوینده: id، نام کوتاه name، نام کامل و عنوان عربی/فارسی
subjectموضوع حدیث (ممکن است نباشد)
arabicمتن عربی با اعراب
arabicPlainمتن عربی بدون اعراب؛ برای جستجو و پردازش
persianترجمه فارسی
notesپی‌نوشت‌های ترجمه، اغلب مأخذ اصلی (فقط اگر وجود داشته باشد)
sourcebook نام کتاب و reference نشانی کامل (جلد و صفحه)
urlصفحه اختصاصی حدیث در حدیث یار

شناسه گویندگان

narratorگویندهتعداد حدیث
0حدیث قدسی۳۰
1پیامبر اکرم صلی الله علیه و آله۲٬۴۲۰
2امیر المؤمنین علی بن ابیطالب (علیه السلام)۱۴٬۳۱۸
3حضرت زهرا سلام الله علیها۲۹
4امام حسن مجتبی (علیه السلام)۷۶
5امام حسین (علیه السلام)۹۸
6امام سجاد (علیه السلام)۲۱۶
7امام محمد باقر (علیه السلام)۸۷۶
8امام جعفر صادق (علیه السلام)۲٬۹۴۴
9امام موسی کاظم (علیه السلام)۲۴۶
10امام رضا (علیه السلام)۳۲۴
11امام جواد (علیه السلام)۸۸
12امام هادی (علیه السلام)۷۹
13امام حسن عسکری (علیه السلام)۹۱
14امام زمان (عج الله تعالی فرجه الشریف)۱۰۰

صفحه‌بندی

فهرست‌ها (مثل /hadis) این قالب را دارند:

{ "items": [ … ], "page": 1, "pageSize": 12, "total": 571, "totalPages": 48 }

خطاها

خطاها با کد وضعیت HTTP مناسب و بدنه‌ای یکسان برمی‌گردند:

{ "error": { "status": 404, "code": "not_found", "message": "حدیثی با شناسه 99999 یافت نشد." } }
وضعیتcodeیعنی
400invalid_parameter، invalid_date، invalid_idsپارامتر نامعتبر؛ پیام خطا دلیل را می‌گوید
404not_found، unknown_endpointحدیث یا مسیر وجود ندارد
400page_limit، too_many_idsعبور از سقف نتایج جستجو یا تعداد شناسه‌های دریافت گروهی
429rate_limitedسقف درخواست در دقیقه پر شده؛ هدر Retry-After را ببینید
429daily_limitسهمیه روزانه حدیث برای این IP تمام شده است

محدودیت و حسن استفاده

حقوق محتوا: منبع احادیث، پایگاه اطلاع‌رسانی حوزه‌نت متعلق به مرکز تحقیقات کامپیوتری علوم اسلامی (نور) است. هرگونه بهره‌برداری مشابه توسط دیگران از محتوای نرم‌افزار، منوط به ارائه مجوز از سوی مرکز نور می‌باشد.
  • سقف ۱۲۰ درخواست در دقیقه و ۵٬۰۰۰ حدیث در روز برای هر IP؛ باقی‌مانده سهمیه در هدر X-Quota-Remaining می‌آید. برای مصرف بیشتر، پاسخ‌ها را کش کنید.
  • هر جستجو حداکثر ۱٬۰۰۰ نتیجه اول را برمی‌گرداند و دریافت گروهی حداکثر ۲۰ شناسه در هر درخواست است. API برای استفاده در اپ و سایت است، نه برداشتن کل مجموعه.
  • «حدیث روز» در طول روز ثابت است؛ کافی است روزی یک بار آن را بگیرید.
  • لطفاً در کنار حدیث، منبع کتاب و پیوندی به حدیث یار بگذارید تا دیگران هم به این گنجینه برسند.
  • هزینهٔ استفاده: سه صلوات برای تعجیل در فرج مولا امام زمان علیه السلام - روحی فداه
  • این سرویس برای همیشه در نسخه v1 پایدار می‌ماند؛ تغییرات ناسازگار فقط در نسخه بعدی (v2) می‌آیند.

نمونه‌کد

// حدیث روز در صفحه وب (یا Node.js 18+)
const res = await fetch("https://hadisyar.ir/api/v1/hadis/day");
const hadis = await res.json();

document.querySelector("#hadis-ar").textContent = hadis.arabic;
document.querySelector("#hadis-fa").textContent = hadis.persian;
document.querySelector("#hadis-src").textContent =
  `${hadis.narrator.name} — ${hadis.source.book}`;

RSS، ابزارک و OpenAPI

خوراک RSS حدیث روز

برای ربات‌های RSS-to-Telegram، خبرخوان‌ها و اتوماسیون‌هایی مثل n8n.

https://hadisyar.ir/feed.xml

ابزارک آماده

صاحب سایت هستید ولی برنامه‌نویس نه؟ ابزارک را با چند کلیک بسازید و کدش را بچسبانید.

ساخت ابزارک

مشخصات OpenAPI 3

برای Postman، Insomnia یا تولید خودکار کلاینت در هر زبانی.

openapi.json

اپلیکیشن آفلاین

همه احادیث بدون اینترنت روی گوشی اندروید.

دریافت از کافه‌بازار

پرسش‌های رایج

API حدیث یار رایگان است؟

بله، بدون نیاز به ثبت‌نام یا کلید است و هزینهٔ استفاده از آن فقط سه صلوات برای تعجیل در فرج مولا امام زمان علیه السلام - روحی فداه است. تنها سقف تعداد درخواست برای هر IP وجود دارد تا سرویس برای همه پایدار بماند.

چطور حدیث روز را با API دریافت کنم؟

یک درخواست GET به /api/v1/hadis/day بفرستید. پاسخ JSON شامل متن عربی، ترجمه فارسی، گوینده و منبع است؛ با format=text هم متن آماده برای پیام‌رسان‌ها می‌گیرید.

آیا می‌توانم حدیث روز را در ربات تلگرام، بله یا ایتا بفرستم؟

بله. خروجی format=text برای ارسال مستقیم در کانال و ربات آماده است و نمونه‌کد ربات کانال در همین صفحه آمده است.

از چه زبان‌هایی می‌شود استفاده کرد؟

از هر زبانی که درخواست HTTP بفرستد: جاوااسکریپت، پایتون، PHP و وردپرس، سی‌شارپ، جاوا، کاتلین و… . CORS هم آزاد است و از مرورگر مستقیم کار می‌کند.

منبع احادیث چیست؟

منبع احادیث پایگاه اطلاع‌رسانی حوزه‌نت متعلق به مرکز تحقیقات کامپیوتری علوم اسلامی (نور) است؛ منبع کتابی هر حدیث هم در پاسخ API آمده است.

Esc
↑ ↓ جابه‌جاییEnter باز کردن/ یا Ctrl K از هر صفحه