پرش به محتوای اصلی
یک شروع رایگان برای شما

۳ روز رایگان،
پنل تحلیلگر را تجربه کنید

ثبت‌نام کنید و با تأیید شماره موبایل، دسترسی آزمایشی سه‌روزه‌تان را فعال کنید.

✓ بدون نیاز به پرداخت✓ فعال‌سازی پس از تأیید موبایل
شروع رایگان ۳ روزه

ویژه کاربران جدید · یک دوره برای هر حساب

فیلتر و جست‌وجوی خبر با پارامترهای API

راهنمای عملی جست‌وجو و فیلتر اخبار با پارامترهای q، sources، categories و بازه زمانی در API فعلی khapi.

تیم khapi · ۹ مرداد ۱۴۰۵ · ۶ دقیقه مطالعه
فیلتر و جست‌وجوی خبر با پارامترهای API

پیش‌نیازها

برای اجرای مثال‌ها به یک کلید فعال 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 امتحان کنید:

آماده شروع هستید؟

۳ روز استفادهٔ رایگان از پنل تحلیلگر، مطابق محدودیت‌های دورهٔ آزمایشی و بدون نیاز به کارت بانکی.