شروع سریع با khapi: دریافت اولین خبر از API در چند دقیقه
در این راهنمای عملی یاد میگیرید چطور کلید API خود را از 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 امتحان کنید:
آماده شروع هستید؟
۳ روز استفادهٔ رایگان از پنل تحلیلگر، مطابق محدودیتهای دورهٔ آزمایشی و بدون نیاز به کارت بانکی.