مستندات API
به مستندات «خبر API» خوش آمدید. با استفاده از این سرویس میتوانید خبرهای گردآوریشده از منابع متصل را جستوجو و فیلتر کنید و خروجی ساختاریافته JSON دریافت کنید. تازگی هر نتیجه به زمان دریافت آن از منبع وابسته است.
https://khapi.ir/api/v1
🔑 احراز هویت (Authentication)
برای استفاده از سرویس، باید کلید API خود را در هدر (Header) تمام درخواستها ارسال کنید.
x-api-key: YOUR_API_KEY
📡 دریافت لیست اخبار
مصرف سهمیه بر مبنای درخواست API است، نه تعداد خبر برگشتی. سقف روزانه و ماهانه حساب را در پنل توسعهدهنده ببینید؛ رسیدن به هر کدام پاسخ ۴۲۹ ایجاد میکند.
متد: GET /news
این اندپوینت آخرین اخبار را بر اساس فیلترهای شما برمیگرداند. نام پارامترها دقیق است: برای محدود کردن تعداد از page_size استفاده کنید.
برای سازگاری با نسخههای قبلی، limit نام جایگزین page_size و source نام جایگزین sources است. مقدار صریح page_size اولویت دارد؛ source فقط در نبود مقدار غیرخالی sources استفاده میشود.
پارامترهای ورودی (Query Params):
در نمایشگر کوچک، برای دیدن همهٔ ستونها جدول را افقی حرکت دهید.
| پارامتر | نوع | توضیحات |
|---|---|---|
sources |
string | نام دقیق منبع مطابق فهرست منابع (مثلاً ISNA)؛ چند منبع با کاما جدا میشوند |
categories |
string | دستهبندی فارسی (مثلاً: ورزشی، سیاسی، فناوری)؛ چند دسته با کاما جدا میشوند |
page_size |
int | تعداد نتایج هر صفحه: ۱ تا ۱۰۰ (پیشفرض: ۱۰) |
q | string | جستوجو در عنوان، متن و برچسبها |
page | int | شماره صفحه، شروع از ۱ |
نمونه درخواست (cURL):
curl -X GET "https://khapi.ir/api/v1/news?page_size=5" \
-H "x-api-key: YOUR_API_KEY"
تاریخ published_at میلادی و بر مبنای UTC است؛ برای نمایش محلی، منطقهٔ زمانی را تبدیل کنید. نمونه پاسخ (JSON):
{
"status": "success",
"total_results": 1,
"page": 1,
"page_size": 5,
"total_pages": 1,
"articles": [
{
"source": "Zoomit",
"title": "هوش مصنوعی جدید گوگل معرفی شد",
"summary": "گوگل امروز از مدل جدید جمینای رونمایی کرد...",
"url": "https://zoomit.ir/...",
"published_at": "2026-11-05T10:30:00",
"image_url": "https://cdn.zoomit.ir/..."
}
]
}
⚠️ مدیریت خطاها
در صورت بروز مشکل، API کدهای استاندارد HTTP را برمیگرداند.
| کد | پیام | علت |
|---|---|---|
401 |
Unauthorized | کلید API نامعتبر یا ارسال نشده است. |
429 |
Too Many Requests | تعداد درخواستهای شما از حد مجاز گذشته است. |