شروع سریع
نشانی پایه همه درخواستها:
https://hadisyar.ir/api/v1
یک درخواست GET ساده کافی است؛ پاسخ JSON با کدگذاری UTF-8 است و متن فارسی و عربی بدون escape برمیگردد:
curl "https://hadisyar.ir/api/v1/hadis/day"
X-Hadis-Date برمیگردد.اندپوینتها
هر روز (به وقت تهران) یک حدیث کوتاه و یکسان برای همه کاربران. مناسب برای «حدیث روز» سایت، ربات و نمایشگر مسجد.
| پارامتر | نوع | توضیح |
|---|---|---|
date |
string | تاریخ میلادی با قالب YYYY-MM-DD؛ پیشفرض: امروز |
narrator |
integer | حدیث روز فقط از یک گوینده خاص (مثلاً 10 برای امام رضا ع) |
format |
string | قالب خروجی: json یا text (متن آماده برای رباتها و پیامک) — پیشفرض json |
در هر درخواست یک حدیث تصادفی؛ با امکان محدود کردن به گوینده، موضوع یا طول متن.
| پارامتر | نوع | توضیح |
|---|---|---|
narrator |
integer | شناسه گوینده (۰ تا ۱۴) — فهرست در /narrators |
subject |
string | نام دقیق موضوع (از /subjects) |
maxLength |
integer | حداکثر تعداد نویسه ترجمه فارسی؛ برای کارتها و استوریها مفید است |
format |
string | قالب خروجی: json یا text (متن آماده برای رباتها و پیامک) — پیشفرض json |
جستجوی تماممتن در ترجمه فارسی، متن عربی (بدون اعراب) و موضوع؛ نسبت به «ی/ي»، «ک/ك»، همزه و نیمفاصله حساس نیست. همه فیلترها اختیاری و ترکیبپذیرند.
| پارامتر | نوع | توضیح |
|---|---|---|
q |
string | عبارت جستجو؛ همه واژهها باید در حدیث باشند |
narrator |
integer | شناسه گوینده (۰ تا ۱۴) — فهرست در /narrators |
subject |
string | نام دقیق موضوع |
source |
string | بخشی از نام کتاب منبع، مثلاً کافی |
page |
integer | شماره صفحه — پیشفرض 1 |
pageSize |
integer | تعداد در هر صفحه (۱ تا 50)؛ page × pageSize حداکثر 1000 — پیشفرض 12 |
ساختار داده
هر حدیث در همه اندپوینتها همین شکل را دارد (نمونه: حدیث شماره ۵۰۰):
{
"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 | پینوشتهای ترجمه، اغلب مأخذ اصلی (فقط اگر وجود داشته باشد) |
source | book نام کتاب و 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 | یعنی |
|---|---|---|
400 | invalid_parameter، invalid_date، invalid_ids | پارامتر نامعتبر؛ پیام خطا دلیل را میگوید |
404 | not_found، unknown_endpoint | حدیث یا مسیر وجود ندارد |
400 | page_limit، too_many_ids | عبور از سقف نتایج جستجو یا تعداد شناسههای دریافت گروهی |
429 | rate_limited | سقف درخواست در دقیقه پر شده؛ هدر Retry-After را ببینید |
429 | daily_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}`;
import requests
r = requests.get(
"https://hadisyar.ir/api/v1/hadis",
params={"q": "صبر", "narrator": 2, "pageSize": 5},
timeout=10,
)
r.raise_for_status()
for h in r.json()["items"]:
print(h["narrator"]["name"], "—", h["persian"])
<?php
// حدیث روز با کش یکساعته — مناسب قالبها و افزونههای وردپرس
$hadis = get_transient('hadisyar_day');
if ($hadis === false) {
$res = wp_remote_get('https://hadisyar.ir/api/v1/hadis/day', ['timeout' => 10]);
$hadis = json_decode(wp_remote_retrieve_body($res), true);
set_transient('hadisyar_day', $hadis, HOUR_IN_SECONDS);
}
echo '<blockquote lang="ar">' . esc_html($hadis['arabic']) . '</blockquote>';
echo '<p>' . esc_html($hadis['persian']) . '</p>';
using System.Net.Http.Json;
using var http = new HttpClient { BaseAddress = new Uri("https://hadisyar.ir/") };
var hadis = await http.GetFromJsonAsync<Hadis>("api/v1/hadis/random?narrator=8");
Console.WriteLine($"{hadis!.Narrator.Name}: {hadis.Persian}");
record Narrator(int Id, string Name);
record Hadis(int Id, string Arabic, string Persian, Narrator Narrator);
# حدیث روز (JSON)
curl "https://hadisyar.ir/api/v1/hadis/day"
# متن آماده برای پیامرسانها و پیامک
curl "https://hadisyar.ir/api/v1/hadis/day?format=text"
# جستجو
curl -G "https://hadisyar.ir/api/v1/hadis" --data-urlencode "q=صبر" -d pageSize=3
# دریافت گروهی
curl -X POST "https://hadisyar.ir/api/v1/hadis/batch" \
-H "Content-Type: application/json" -d "[12, 500, 9000]"
# ارسال خودکار حدیث روز به کانال تلگرام یا بله — روزی یک بار با cron اجرا کنید
import requests
TOKEN = "<bot-token>"
CHAT = "@your_channel"
API = f"https://api.telegram.org/bot{TOKEN}" # بله: f"https://tapi.bale.ai/bot{TOKEN}"
text = requests.get("https://hadisyar.ir/api/v1/hadis/day",
params={"format": "text"}, timeout=10).text
requests.post(f"{API}/sendMessage", data={"chat_id": CHAT, "text": text}, timeout=10)
RSS، ابزارک و OpenAPI
خوراک RSS حدیث روز
برای رباتهای RSS-to-Telegram، خبرخوانها و اتوماسیونهایی مثل n8n.
https://hadisyar.ir/feed.xmlابزارک آماده
صاحب سایت هستید ولی برنامهنویس نه؟ ابزارک را با چند کلیک بسازید و کدش را بچسبانید.
ساخت ابزارکپرسشهای رایج
API حدیث یار رایگان است؟
بله، بدون نیاز به ثبتنام یا کلید است و هزینهٔ استفاده از آن فقط سه صلوات برای تعجیل در فرج مولا امام زمان علیه السلام - روحی فداه است. تنها سقف تعداد درخواست برای هر IP وجود دارد تا سرویس برای همه پایدار بماند.
چطور حدیث روز را با API دریافت کنم؟
یک درخواست GET به /api/v1/hadis/day بفرستید. پاسخ JSON شامل متن عربی، ترجمه فارسی، گوینده و منبع است؛ با format=text هم متن آماده برای پیامرسانها میگیرید.
آیا میتوانم حدیث روز را در ربات تلگرام، بله یا ایتا بفرستم؟
بله. خروجی format=text برای ارسال مستقیم در کانال و ربات آماده است و نمونهکد ربات کانال در همین صفحه آمده است.
از چه زبانهایی میشود استفاده کرد؟
از هر زبانی که درخواست HTTP بفرستد: جاوااسکریپت، پایتون، PHP و وردپرس، سیشارپ، جاوا، کاتلین و… . CORS هم آزاد است و از مرورگر مستقیم کار میکند.
منبع احادیث چیست؟
منبع احادیث پایگاه اطلاعرسانی حوزهنت متعلق به مرکز تحقیقات کامپیوتری علوم اسلامی (نور) است؛ منبع کتابی هر حدیث هم در پاسخ API آمده است.