فیلتر و جستوجوی خبر با پارامترهای API
راهنمای عملی جستوجو و فیلتر اخبار با پارامترهای q، sources، categories و بازه زمانی در API فعلی khapi.
پیشنیازها
برای اجرای مثالها به یک کلید فعال khapi نیاز دارید. کلید باید در هدر `x-api-key` ارسال شود و نباید در کد سمت کاربر یا مخزن عمومی قرار بگیرد.
مسیر فعلی دریافت اخبار:
GET https://khapi.ir/api/v1/news
پارامترهای اصلی
- `q`: جستوجوی آزاد در عنوان و متن خبر
- `q_in_title`: محدودکردن جستوجو به عنوان
- `sources`: یک یا چند منبع بهصورت کاماجدا
- `categories`: یک یا چند دسته بهصورت کاماجدا
- `from_date` و `to_date`: بازه زمانی با فرمت `YYYY-MM-DD`
- `sort_by`: یکی از مقادیر `published_at` یا `relevancy`
- `page`: شماره صفحه از ۱
- `page_size`: تعداد نتیجه در هر صفحه، حداکثر ۱۰۰
نام پارامترهای `sources` و `categories` جمع است. استفاده از `source`، `category` یا `limit` در این endpoint نتیجه مورد انتظار را تولید نمیکند.
مثال با curl
در این مثال خبرهایی که عبارت «تورم» دارند، از دو منبع مشخص و در یک بازه زمانی دریافت میشوند:
curl --get "https://khapi.ir/api/v1/news" \
-H "x-api-key: YOUR_API_KEY" \
--data-urlencode "q=تورم" \
--data-urlencode "sources=ایسنا,فارس" \
--data-urlencode "from_date=2026-08-01" \
--data-urlencode "to_date=2026-08-17" \
--data-urlencode "page=1" \
--data-urlencode "page_size=20"
مثال با Python
import os
import requests
api_key = os.environ["KHAPI_API_KEY"]
response = requests.get(
"https://khapi.ir/api/v1/news",
headers={"x-api-key": api_key},
params={
"q": "تورم",
"sources": "ایسنا,فارس",
"categories": "اقتصادی",
"from_date": "2026-08-01",
"to_date": "2026-08-17",
"sort_by": "published_at",
"page": 1,
"page_size": 20,
},
timeout=20,
)
response.raise_for_status()
payload = response.json()
for article in payload.get("articles", []):
print(article["published_at"], article["source"], article["title"])
صفحهبندی درست
پاسخ API شامل `page`، `page_size`، `total_pages` و آرایه `articles` است. برای پردازش حجم بالا، صفحهها را یکییکی دریافت کنید و بعد از رسیدن به `total_pages` متوقف شوید.
page = 1
while True:
response = requests.get(
"https://khapi.ir/api/v1/news",
headers={"x-api-key": api_key},
params={"q": "بازار سرمایه", "page": page, "page_size": 100},
timeout=20,
)
response.raise_for_status()
data = response.json()
for article in data.get("articles", []):
process(article)
if page >= data.get("total_pages", page):
break
page += 1
خطاهای رایج
- ارسالنکردن `x-api-key` پاسخ ۴۰۱ ایجاد میکند.
- کلید نامعتبر یا غیرفعال پاسخ ۴۰۳ میدهد.
- برای محدودیت نرخ باید پاسخ ۴۲۹ را با retry و تأخیر تصاعدی مدیریت کنید.
- مقدارهای منبع و دسته را مطابق نامهای موجود در داده khapi ارسال کنید.
- تاریخ شروع نباید بعد از تاریخ پایان باشد.
گام بعدی
پس از ساخت یک فیلتر دقیق، میتوانید همان منطق را در پنل تحلیلگر به پایش ذخیرهشده تبدیل کنید یا خروجی Excel، PDF و تصویر بگیرید.
این مطلب چطور به کار شما بیاید؟
مفاهیم این مقاله را مستقیم در پنل khapi امتحان کنید:
آماده شروع هستید؟
۳ روز استفادهٔ رایگان از پنل تحلیلگر، مطابق محدودیتهای دورهٔ آزمایشی و بدون نیاز به کارت بانکی.