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

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

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

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

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

شروع سریع با khapi: دریافت اولین خبر از API در چند دقیقه

در این راهنمای عملی یاد می‌گیرید چطور کلید API خود را از khapi دریافت کنید، اولین درخواست API را ارسال کنید و داده‌های خبری را در پروژه‌تان نمایش دهید.

تیم khapi · ۹ مرداد ۱۴۰۵ · ۵ دقیقه مطالعه
شروع سریع با khapi: دریافت اولین خبر از API در چند دقیقه

API خبر khapi چیست؟

khapi یک API خبری است که اخبار فارسی را به‌صورت ساخت‌یافته و قابل‌برنامه‌نویسی در اختیار شما قرار می‌دهد. با استفاده از آن می‌توانید جست‌وجو، فیلتر و دریافت اخبار را در برنامه، داشبورد یا ربات خود خودکار کنید.

در این راهنما گام‌به‌گام از دریافت کلید دسترسی تا ارسال اولین درخواست و نمایش نتیجه پیش می‌رویم.

دریافت کلید API

پس از ورود به پنل khapi، از بخش تنظیمات توسعه‌دهندگان یک API Key ایجاد کنید. این کلید را در هدر درخواست‌های خود ارسال می‌کنید.

کلید را در کد سمت‌کلاینت، مخزن عمومی یا فایل‌های قابل‌دسترسی عمومی قرار ندهید. در محیط production آن را در یک متغیر محیطی یا سیستم مدیریت راز نگه دارید.

ارسال اولین درخواست با curl

khapi احراز هویت را با هدر `x-api-key` انجام می‌دهد. نمونهٔ کامل درخواست به این صورت است:

curl -X GET "https://khapi.ir/api/v1/news?page_size=10" \
  -H "x-api-key: YOUR_API_KEY"

در پاسخ، آخرین اخبار با سقف تعداد مشخص‌شده برمی‌گردند. ساختار پاسخ دقیقاً مطابق نمونهٔ زیر است:

{
  "status": "success",
  "total_results": 222609,
  "page": 1,
  "page_size": 10,
  "total_pages": 22261,
  "articles": [
    {
      "id": 267126,
      "source": "Mehr News",
      "title": "عنوان نمونه خبر",
      "summary": "خلاصه کوتاه خبر",
      "url": "https://example.com/news/6904713",
      "image_url": "https://example.com/img/1.jpg",
      "published_at": "2026-07-31T22:46:22",
      "tags": ["برچسب ۱", "برچسب ۲"],
      "categories": ["اقتصادی"],
      "entities": ["سازمان (organization)"]
    }
  ]
}

فیلدهای اصلی هر خبر عبارت‌اند از: `id`، `source`، `title`، `summary`، `url`، `image_url`، `published_at`، `tags`، `categories` و `entities`.

دریافت خبر با Python

برای استفاده در بک‌اند، تحلیل داده یا pipelineهای ETL، نمونهٔ زیر با کتابخانه `requests` نوشته شده است:

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={"page_size": 10},
    timeout=20,
)

response.raise_for_status()
payload = response.json()

for article in payload["articles"]:
    print(article["title"])
    print("  منبع:", article["source"])
    print("  لینک:", article["url"])
    print("  زمان:", article["published_at"])

همیشه خطاهای شبکه را مدیریت کنید، از `raise_for_status()` استفاده کنید و برای پاسخ‌های ۴۲۹ (محدودیت نرخ) مکانیزم retry با تاخیر تصاعدی در نظر بگیرید.

دریافت خبر در Next.js 14

در پروژه‌های Next.js، درخواست را از سمت سرور (Route Handler) انجام دهید تا کلید API فاش نشود. نمونهٔ کامل و معتبر:

import { NextResponse } from "next/server";

export async function GET() {
  const response = await fetch(
    "https://khapi.ir/api/v1/news?page_size=10",
    {
      headers: {
        "x-api-key": process.env.KHAPI_API_KEY as string,
      },
      next: { revalidate: 300 },
    },
  );

  if (!response.ok) {
    return NextResponse.json(
      { error: "دریافت خبرها با خطا مواجه شد." },
      { status: response.status },
    );
  }

  const data = await response.json();
  return NextResponse.json(data.articles ?? []);
}

کلید را در فایل `.env.local` نگه دارید و آن را هرگز commit نکنید:

KHAPI_API_KEY=your_api_key_here

پارامترهای درخواست

API از پارامترهای زیر پشتیبانی می‌کند:

  • `q`: جست‌وجوی آزاد در عنوان و محتوا
  • `q_in_title`: فقط توی عنوان
  • `sources`: فیلتر با نام منبع (کاما‑جدا، مثلاً `ایسنا,فارس`)
  • `categories`: فیلتر دسته‌بندی موضوعی (کاما‑جدا، مثلاً `اقتصادی,فناوری`)
  • `entities`: فیلتر بر اساس موجودیت (AND)
  • `from_date` / `to_date`: محدوده تاریخ (فرمت `YYYY-MM-DD`)
  • `sort_by`: `published_at` یا `relevancy`
  • `page` / `page_size`: صفحه‌بندی

گام بعدی

اکنون اولین اتصال شما برقرار شده است. برای محدودکردن نتایج بر اساس کلیدواژه، منبع یا بازه زمانی، راهنمای فیلتر و جست‌وجو را بخوانید و داده‌ها را وارد محصول خود کنید.

اشتراک‌گذاری:

این مطلب چطور به کار شما بیاید؟

مفاهیم این مقاله را مستقیم در پنل khapi امتحان کنید:

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

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