دسترسی آزاد به گنجینه اشعار شاعران بزرگ فارسی، فقط با یک درخواست HTTP.
بدون ثبتنام. بدون کلید API. بدون محدودیت پرداخت. متنباز با مجوز MIT.
API اشعار فارسی یک سرویس REST عمومی و رایگان برای دسترسی به اشعار کلاسیک و معاصر فارسی است. این پروژه شامل اشعار مولانا، حافظ، سعدی، فردوسی، نیما یوشیج، سهراب سپهری، و سخنان بیش از ۴۹۰ بزرگ تاریخ است.
ویجت قابل تعبیه، صفحه مستندات تعاملی، نمونههای کاربردی با اجرای زنده، و موتور API اختصاصی (Tigh) از قابلیتهای این پروژه هستند.
یک شعر تصادفی:
curl https://pq.arsamadineh.ir/api/quotes?random=true&limit=1یک غزل حافظ برای فال:
curl https://pq.arsamadineh.ir/api/quotes/hafez?random=true&limit=1جستجو در میان اشعار:
curl "https://pq.arsamadineh.ir/api/quotes/search?q=عشق&limit=5"نمونه پاسخ:
{
"success": true,
"data": [
{
"id": 1,
"text_persian": "عاشقان مردهاند در عشق زنده\nتا ابد در دل جانان پاینده",
"text_english": "Lovers are dead in love, yet alive / Forever enduring in the beloved's heart",
"poet": "مولانا جلالالدین رومی",
"poet_english": "Rumi",
"source": "دیوان شمس",
"category": "عشق"
}
],
"count": 1
}| روش | مسیر | توضیح |
|---|---|---|
GET |
/api/quotes |
فهرست اشعار با فیلتر شاعر و موضوع |
GET |
/api/quotes/[poet] |
اشعار یک شاعر مشخص |
GET |
/api/quotes/category/[category] |
اشعار یک موضوع مشخص |
GET |
/api/quotes/hafez |
دیوان کامل حافظ (۴۹۷ غزل) |
GET |
/api/quotes/shereno |
بیش از چهار هزار اثر شعر نو |
GET |
/api/quotes/non-poetry |
سخنان ۴۹۰+ بزرگ تاریخ |
GET |
/api/quotes/search |
جستجوی پیشرفته در متن اشعار |
GET |
/api/poets |
فهرست شاعران |
GET |
/api/categories |
دستهبندیهای موضوعی |
GET |
/api/stats |
آمار کلی پایگاه داده |
GET |
/api/embed |
ویجت HTML قابل تعبیه |
GET |
/api/engine/stats |
متریک زنده موتور Tigh |
GET |
/api/engine/benchmark |
بنچمارک عملکردی موتور |
| پارامتر | نوع | پیشفرض | توضیح |
|---|---|---|---|
random |
boolean |
false |
دریافت تصادفی |
limit |
number |
10 |
تعداد نتایج (حداکثر ۱۰۰) |
poet |
string |
- | فیلتر نام شاعر |
category |
string |
- | فیلتر موضوع |
q |
string |
- | عبارت جستجو |
lang |
string |
fa |
زبان جستجو (fa/en/both) |
پروژه شامل یک موتور API اختصاصی به نام Tigh است که زیرساخت پردازش درخواستها را مدیریت میکند:
| ماژول | عملکرد |
|---|---|
| Trie Router | مسیریابی سریع با پشتیبانی از پارامترهای داینامیک و wildcard |
| LRU Cache | کش درونبرنامهای با TTL و ردیابی دسترسی O(1) |
| Rate Limiter | محدودسازی نرخ با سه الگوریتم: Token Bucket، Sliding Window، Fixed Window |
| Circuit Breaker | مدار شکن خودترمیمشونده با سه حالت closed/open/half-open |
| Metrics | جمعآوری متریک با حافظه حلقهای: P50/P99 latency، hit rate، uptime |
| Middleware | پایپلاین CORS، اندازهگیری زمان، و فشردهسازی gzip |
| مسیر | توضیح |
|---|---|
/ |
صفحه اصلی با معرفی و نمونه تعاملی API |
/docs |
مستندات کامل اندپوینتها با جستجوی سراسری (Ctrl K) |
/examples |
نمونه کد در چهار زبان با اجرای زنده |
/embed |
سازنده ویجت با پیشنمایش آنی و کد تعبیه |
/sakhtar |
نمایش معماری موتور Tigh با نمودار و متریک زنده |
/contribute |
فرم مشارکت برای افزودن شعر جدید |
/changelog |
تاریخچه تغییرات نسخهها |
/privacy |
سیاست حریم خصوصی |
/terms |
شرایط استفاده |
ویجت اشعار فارسی را میتوانید با تنظیمات دلخواه بسازید و در وبسایت خود قرار دهید:
<iframe
src="https://pq.arsamadineh.ir/api/embed?theme=elegant&size=medium"
width="100%"
height="400"
frameborder="0"
scrolling="no"
>
</iframe>پارامترهای موجود: theme (default/elegant/minimal/classic/modern)، size (small/medium/large)، poet، category، english، source، category_badge، auto_refresh، refresh_interval.
app/
api/ اندپوینتهای REST
quotes/ دریافت اشعار
embed/ ویجت HTML
engine/ متریک و بنچمارک موتور
poets/ فهرست شاعران
categories/ دستهبندیها
stats/ آمار پایگاه داده
docs/ مستندات تعاملی
examples/ نمونههای کاربردی
embed/ سازنده ویجت
sakhtar/ معماری موتور Tigh
contribute/ فرم مشارکت
changelog/ صفحه تغییرات
privacy/ سیاست حریم خصوصی
terms/ شرایط استفاده
lib/
engine/ موتور Tigh
engine.ts هسته اصلی
router.ts مسیریاب Trie
cache.ts کش LRU با ایندکس نقشهای
rate-limiter.ts محدودسازی نرخ (سه الگوریتم)
circuit-breaker.ts مدار شکن خودترمیم
metrics.ts متریک با حافظه حلقهای
middleware.ts CORS، زمانسنجی، فشردهسازی
adapter-next.ts اداپتور Next.js
instance.ts نمونه سراسری موتور
types.ts تعریف انواع
data/ فایلهای JSON اشعار
poetry-quotes.json اشعار کلاسیک
hafez.json دیوان حافظ (۴۹۷ غزل)
shereno.json شعر نو (۴۰۰۰+ اثر)
non-poetry-quotes.json سخنان بزرگان (۴۹۰+)
changelog.ts منبع حقیقتی تغییرات
utils.ts توابع مشترک (cn، formatVerse)
components/
navbar.tsx نوار ناوبری شیشهای
footer.tsx فوتر مشترک
quote-cards/ کارتهای نمایش شعر
ui/ کامپوننتهای پایه
public/
banner.svg بنر اصلی پروژه
og-image.svg تصویر Open Graph
twitter-card.svg تصویر Twitter Card
icon.svg فاوآیکن
پیشنیازها: Node.js ۱۸+ و یکی از npm، pnpm، یا bun.
git clone https://github.com/arsamadineh/Persian-Quote-API.git
cd Persian-Quote-API
npm install
npm run devپروژه روی http://localhost:3000 در دسترس خواهد بود.
روش آسان: فرم تعاملی در /contribute — بدون نیاز به دانش برنامهنویسی، فقط متن شعر را وارد کنید.
روش مستقیم: مخزن را fork کنید، شاخه جدید بسازید، تغییرات را در lib/changelog.ts ثبت کنید، و PR ارسال کنید.
پیش از مشارکت، فایل AGENTS.md را مطالعه کنید.
این پروژه تحت مجوز MIT منتشر شده است. اشعار موجود در پایگاه داده در حوزه مالکیت عمومی قرار دارند.
این پروژه بهطور کامل توسط آرسام آدینه و با هزینه شخصی توسعه و نگهداری میشود. اگر برایتان مفید بود، با خرید یک قهوه از ادامه کار حمایت کنید:
این پروژه توسط آرسام آدینه (Arsam Adineh) طراحی، توسعه، و تامین مالی شده است.
- وبسایت: arsamadineh.ir
- گیتهاب: github.com/arsamadineh
- X: x.com/dev_arsam
- تلگرام: t.me/arsamadineh
- ایمیل: contact@arsamadineh.ir
- مخزن: arsamadineh/Persian-Quote-API
- گزارش مشکل: Issues
- تغییرات: lib/changelog.ts