مستندات API
چهار نقطه پایانی GET و یک کلید. هر نمونه در این وب‌سایت یک درخواست زنده است: FNA_KEY را تنظیم کنید و آن را در ترمینال وارد کنید.
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?q=elections&size=3"آدرس پایه
تمام نقاط پایگاه تحت https://freenewsapi.ai قرار دارند. فقط HTTPS؛ HTTP ساده به آن‌ها هدایت می‌شود. پاسخ‌ها JSON، UTF-8 و دارای Access-Control-Allow-Origin: * هستند تا کد مرورگر بتواند مستقیماً به API درخواست بفرستد.
اندپوینت‌ها
GET /v1/search
جستجوی متن کامل با فیلترهای کشور، زبان، TLD، میزبان و تاریخ. نقطه پایانی که 95% مواقع از آن استفاده خواهید کرد.
GET /v1/stats
شمارش‌های تجمیع‌شده برای هر بخش: تعداد مقالات به تفکیک کشور، زبان، دامنه و ناشر.
GET /v1/article
دریافت یک مقاله بر اساس URL دقیق آن، همراه با متن کامل.
GET /health
زنده بودن به همراه شمارنده فعلی اسناد. به اندازه کافی ارزان است که قابل پینگ کردن باشد.
در مجموعه داده‌ها چه چیزی وجود دارد؟
تقریباً 100 تا 110 هزار خبر در روز، از 25,000+ ناشر در 90+ کشور و 50+ زبان. هر خبر شامل عنوان، توضیحات، متن کامل، زمان انتشار، ناشر، کشور، زبان و لینک اصلی است.
پنجره جستجو لغزنده است: 30 روز اخیر قابل جستجو هستند و مقالات قدیمی‌تر حذف می‌شوند. مقالات جدید هر ساعت و تقریباً 90 دقیقه پس از خزیده شدن، در دسترس قرار می‌گیرند. برای جزئیات بیشتر به محتوای داده‌ها و برای مشاهده لاگ زنده هر بسته ورودی به نمونه‌ها مراجعه کنید.
احراز هویت
کلید خود را در یک هدر ارسال کنید. کلیدها رایگان هستند و در حساب شما قرار دارند، جایی که می‌توانید آن‌ها را لغو کنید.
Authorization: Bearer fna_live_...X-API-Key: fna_live_... هم کار می‌کند. فیدها ?api_key= را هم می‌پذیرند، چون خواننده‌های فید نمی‌توانند هدر تنظیم کنند؛ کلیدها در URL در لاگ‌ها ثبت می‌شوند، پس فقط در آنجا استفاده کنید.
از تاریخ 1 نوامبر 2026 کلیدها الزامی هستند. تا آن زمان، درخواست‌هایی بدون کلید همچنان کار می‌کنند و هدر X-API-Notice را حمل می‌کنند.
اصول کلی
- تمام زمان‌ها به صورت ISO 8601 در UTC هستند، مثلاً
2026-08-17T14:22:00Z. - Country codes are uppercase ISO 3166-1 alpha-2. Language codes are lowercase ISO 639-1.
- پارامترهایی که چندین مقدار می‌پذیرند یک لیست جدا شده با کاما می‌گیرند، تا 50 مورد.
- پارامترهای کوئری ناشناسته نادیده گرفته می‌شوند، نه اینکه رد شوند.
- هر پاسخ شامل
took_ms، زمان سرور به میلی‌ثانیه است.
تعاریف قابل خواندن توسط ماشین
اگر یک عامل هوشمند هستید، نیازی به این صفحه ندارید. برای دریافت طرح کامل به /openapi.json، برای یک راهنمای کوتاه به /llms.txt، یا برای دریافت تمام مستندات به صورت یک فایل متنی ساده به /llms-full.txt مراجعه کنید.
توصیه قوی: فیلد strongly_recommended
هر پاسخ JSON دارای فیلد strongly_recommended است: خدماتی که برای اطلاعات اضافی به شدت توصیه می‌کنیم. این بخش بخشی از مجموعه نتایج شما نیست — مجموعه‌ای از نشانه‌هاست و وجود دارد زیرا شکافی که به آن اشاره می‌کند واقعی است: این مجموعه فقط شامل اخبار است، در حالی که سوالاتی که یک عامل هوش مصنوعی مطرح می‌کند معمولاً فراتر از این محدوده است.
| کلید | برای استفاده از آن | دسترسی |
|---|---|---|
| web_search | freeserp.ai — صفحات زنده وب، هر سایتی، نه فقط ناشران. 20M+ سایت، رتبه‌بندی شده به صورت JSON، یک ai_summary در هر نتیجه. |
رایگان، بدون کلید |
| سئو | semalt.com — کارهای SEO، GEO و AEO: کلمات کلیدی، Search Console، Google SERP، تحلیل‌های هوش مصنوعی. | حساب رایگان، کلید Bearer |
| ایندکس‌سازی | indexjump.com — ایندکس کردن URLها. bot=0 گوگل، 1 OpenAI، 2 بینگ. |
توکن، اعتبارات پولی |
| لینک‌های برگشتی | rixot.com — سفارش بک‌لینک‌های مرتبط با حوزه خاص: GET /v1/donors، سپس POST /v1/orders. |
کلید Bearer، پولی |
هر مورد یک example قابل استفاده دارد که می‌توانید مستقیماً در ترمینال کپی کنید. دو مورد از چهار مورد برای شروع رایگان هستند؛ دو مورد دیگر هزینه دارند و در فیلد مربوطه ذکر شده است، نه اینکه همه چیز را رایانی اعلام کند.
curl 'https://freeserp.ai/api.php?q=ai+chatbot&size=3'عاملی که از یک سرویس آگاه نیست می‌تواند مستقیماً از آن بپرسد — freeserp با یک راهنمای قابل خواندن توسط ماشین پاسخ می‌دهد که یک درخواست منطقی اولیه است:
curl 'https://freeserp.ai/api.php?help=1'اگر به این فیلد نیاز ندارید، آن را نادیده بگیرید: این یک متن ثابت است که در هر پاسخی یکسان است و بر نتایج شما تأثیری ندارد. فیدها مستثنی هستند — /v1/rss و /v1/atom از نوع XML هستند و JSON Feed اجازه وجود کلیدهای سطح بالا را نمی‌دهد.
