Free News API: جستجوی متن کامل بر روی ۲۱ میلیون مقاله، ۲۵٬۰۰۰ ناشر و ۱۰۰ کشور — بدون هیچ کلیدی

APIهای خبری API معمولاً بر اساس درخواست فروخته می‌شوند، پشت یک کلید قرار دارند و در طرح رایگان، محدود به صد درخواست در روز هستند. Free News API هیچ‌یک از این محدودیت‌ها را ندارد: ۲۱.۵ میلیون مقاله در یک پنجره ۹۰ روزه متحرک، بیش از ۲۵٬۰۰۰ ناشر، بدون کلید، بدون ثبت‌نام، بدون سهمیه و با اجازه استفاده تجاری. در اینجا تمام امکانات — جستجو، آمار، روندها، بازارها، فیدها و MCP — و همچنین بررسی صادقانه‌ای از اینکه این داده‌ها در چه مواردی نادرست عمل می‌کنند، ارائه شده است.

شکل مسئله

از یک عامل هوش مصنوعی بپرسید که دنیا در حال حاضر درباره چه چیزی می‌نویسد و سه گزینه بد پیش رو دارد. می‌تواند مستقیماً ناشران را اسکرپ (Scrape) کند که شکننده، کند و از نظر حقوقی مبهم است. می‌تواند به یک API خبری API تجاری متصل شود که به معنای داشتن حساب کاربری، کلید، صورت‌حساب ماهانه و — در تمام طرح‌های رایگان موجود در بازار — محدودیت صد درخواست در روز و تأخیر ۲۴ ساعته در دسترسی به مقالات است. یا می‌تواند از روی داده‌های آموزشی که ماه‌ها پیش متوقف شده‌اند، حدس بزند.

Free News API هزینه و کاغذبازی گزینه میانی را بدون از دست دادن قابلیت‌های آن حذف می‌کند. یک درخواست GET، بدون نیاز به اعتبارنامه، بر روی مجموعه‌ای که در زمان نگارش این متن شامل ۲۱٬۵۵۷٬۰۴۴ مقاله از بیش از بیست و پنج هزار ناشر است، انجام می‌شود؛ این مجموعه در یک پنجره ۹۰ روزه متحرک نگهداری و به‌طور پیوسته به‌روز می‌شود — جدیدترین مقاله در این ایندکس معمولاً کمتر از دو دقیقه قدمت دارد.

چهار نقطه پایانی اصلی و موارد دیگر

هسته سرویس شامل چهار نقطه پایانی GET است که همگی تحت https://freenewsapi.ai قرار دارند، همگی پاسخ‌های UTF-8 JSON را با هدر Access-Control-Allow-Origin: * برمی‌گردانند تا کد مرورگر بتواند مستقیماً آن‌ها را فراخوانی کند و همگی زمان سمت سرور را در took_ms گزارش می‌دهند.

در اطراف هسته‌ی اصلی، چهار خانواده‌ی دیگر قرار دارند که هر کدام می‌توانند به‌تنهایی یک محصول مستقل باشند: روندها (خوشه‌بندی داستان‌های زنده بر اساس کشور)، بازارها (سری‌های قیمت هم‌راستا با حجم پوشش خبری)، احساسات کریپتو (یک بلاک بیت‌کوین با هفت نقطه پایانی)، و توزیع مجدد (همان جستجو که به‌صورت RSS، Atom یا فید JSON ارائه می‌شود). درباره‌ی همه‌ی آن‌ها در ادامه صحبت خواهیم کرد.

curl "https://freenewsapi.ai/v1/search?q=climate+summit&size=2"

{
  "took_ms": 41,
  "total": 1284,
  "total_is_lower_bound": false,
  "size": 2,
  "offset": 0,
  "results": [
    {
      "id": "9c1f8a4b2d3e5f6071829304a5b6c7d8",
      "url": "https://example-news.com/world/climate-summit-opens",
      "title": "Climate summit opens with a call for binding targets",
      "description": "Delegates from 190 countries gathered on Monday ...",
      "published_at": "2026-08-17T09:12:00Z",
      "crawled_at": "2026-08-17T10:48:31Z",
      "host": "example-news.com",
      "sitename": "Example News",
      "country": "GB",
      "country_source": "cctld",
      "lang": "en",
      "tld": "com"
    }
  ]
}

سه فیلد در این پاسخ شایسته‌ی توجه فوری هستند، زیرا صداقت کل مجموعه داده را نشان می‌دهند. total_is_lower_bound به شما اطلاع می‌دهد که آیا تعداد مطابقت‌ها به سقف ۱۰,۰۰۰ رسیده و شمارش متوقف شده است یا خیر. country_source به شما می‌گوید کشور چگونه تعیین شده است — زیرا در هر مجموعه داده‌ی خبری، بخش بزرگی از مقادیر کشور بر اساس استنباط هستند، نه واقعیت‌های قطعی. و crawled_at نشانگر زمان قابل اعتماد است: ناشران معمولاً published_at را به‌صورت دستی به عقب برمی‌گردانند، اما زمان خزیدن توسط پایپ‌لاین تعیین می‌شود و تنها رو به جلو حرکت می‌کند.

جستجو: هر پارامتری که اهمیت دارد

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

پرس‌وجو (Query)

• q مطابقت با عنوان (وزن ۳)، توضیحات (وزن ۲) و متن مقاله. معنای AND — هر اصطلاحی باید حضور داشته باشد، بنابراین افزودن یک کلمه، دامنه‌ی جستجو را باریک‌تر می‌کند تا گسترش‌تر. حداکثر ۵۰۰ کاراکتر.

فیلترها

فیلترها با AND بین پارامترها و OR درون یک پارامتر ترکیب می‌شوند. بنابراین country=DE,AT&lang=de به معنای «مقالات به زبان آلمانی از آلمان یا اتریش» خوانده می‌شود. هر فیلتر یک لیست جداشده با کاما از حداکثر پنجاه مقدار را می‌پذیرد.

کنترل خروجی

curl "https://freenewsapi.ai/v1/search?country=UA&lang=uk&date=today&sort=date&size=10"

curl "https://freenewsapi.ai/v1/search?q=merger&country=DE&date=48h&sort=date&size=20"

شمارش پیش از جستجو

مهم‌ترین اندپوینت که کمتر مورد استفاده قرار می‌گیرد، /v1/stats است. اغلب سوال مفید این نیست که «مقالات چیست؟» بلکه «آیا اصلاً چیزی در اینجا وجود دارد و کجاست؟» شمارش نتایج با کسری از هزینه — حدود دوصد توکن در مقابل چندین هزار توکن برای یک صفحه نتایج — آن را به اولین تماس صحیح برای عاملی تبدیل می‌کند که تصمیم می‌گیرد آیا اجرای جستجو ارزش دارد یا خیر.

curl "https://freenewsapi.ai/v1/stats?q=earthquake&date=7d"

این اندپوینت شمارش‌ها را بر اساس کشور، زبان، TLD، ناشر و روز باز می‌گرداند که بر کل مجموعه تطبیق‌یافته محاسبه می‌شود، نه فقط صفحه فعلی. که همچنین روشی است که با آن پوشش را پیش از اعتماد به آن اندازه‌گیری می‌کنید. نمای بدون فیلتر در زمان نگارش:

کشورهای برتر

زبان‌های برتر

انگلیسی ۵٬۵۱۳٬۶۵۰ · اسپانیایی ۲٬۶۹۹٬۴۵۷ · روسی ۱٬۷۸۵٬۷۹۶ · ترکی ۱٬۵۰۱٬۰۰۴ · ایتالیایی ۹۹۲٬۲۰۰ · آلمانی ۷۳۳٬۶۷۷ · فرانسوی ۶۸۹٬۱۳۶ · عربی ۶۶۴٬۰۱۶ · پرتغالی ۶۳۷٬۶۰۷ · هندی ۵۶۰٬۸۴۰ · یونانی ۴۶۶٬۵۰۴ · ژاپنی ۴۲۷٬۰۸۵ · ویتنامی ۳۸۵٬۷۱۹ · رومانیایی ۳۵۸٬۷۶۶ · چینی ۳۵۲٬۷۲۰ · اوکراینی ۳۴۵٬۸۰۹ · کره‌ای ۳۳۵٬۰۷۹ · فارسی ۲۶۸٬۱۲۶ · لهستانی ۲۳۸٬۹۰۴ · بلغاری ۱۸۳٬۲۰۴.

این توزیع ارزش آن را دارد که برای لحظه‌ای به آن خیره شوید، زیرا دقیقاً برعکس چیزی است که بیشتر خبرگزاری‌های API به شما ارائه می‌دهند. مجموعه داده‌های معمول که انگلیسی‌محور و ایالات متحده‌محور هستند، در اینجا صدای نمی‌دهند: هند بر ایالات متحده پیشی دارد، ترکی بر آلمانی، و یونانی، ویتنامی، فارسی و بلغاری همگی نمایندگان شش‌رقمی دارند. اگر پرسش شما درباره مطبوعات غیرانگلیسی است، این یک مجموعه داده کاملاً متفاوت است.

حجم

منحنی روزانه در by_day کل پنجره نود روزه را پوشش می‌دهد. روزهای اخیر در محدوده تقریبی ۴۰۰٬۰۰۰ تا ۷۰۰٬۰۰۰ مقاله در روز قرار دارند؛ در اوایل این پنجره، پیش از اینکه لایه RSS به همراه ورودی آرشیو اضافه شود، حجم روزانه بین ۱۳۰٬۰۰۰ تا ۲۳۰٬۰۰۰ بود. هر دو رقم در یک پاسخ قابل مشاهده هستند که همان نکته اصلی است — سرویس روند رشد خود را به شما نشان می‌دهد، نه میانگین تبلیغاتی را.

روندها: مطبوعات در حال حاضر واقعاً درباره چه چیزی گزارش می‌دهند

جستش به پرسش «درباره X چه چیزی نوشته شده است» پاسخ می‌دهد. روندها به پرسش متفاوت و اغلب بهتری پاسخ می‌دهد: «چه اتفاقی در حال رخ دادن است» — بدون نیاز به X.

یک ربات مقالات را بر اساس کشور به داستان‌ها خوشه‌بندی کرده و آن‌ها را به‌روز نگه می‌دارد. هر پنج دقیقه مقالات جدید با استفاده از کلمات شناسه‌کننده‌شان به داستان‌های شناخته‌شده متصل می‌شوند، بدون هیچ فراخوانی مدل؛ هر چند ساعت یک کشور یک دور کامل را طی می‌کند که در آن یک مدل زبانی تیترها را می‌خواند و داستان‌ها را از نو نام‌گذاری می‌کند. در زمان نگارش این متن، لایه روندها ۱۱۵ کشور را پوشش می‌دهد که هر کدام در چند دقیقه اخیر دوباره محاسبه شده‌اند.

curl "https://freenewsapi.ai/v1/trends?country=US&window=24h&size=5"

{
  "window": "24h",
  "filters": { "country": ["US"], "min_publishers": 1 },
  "trends": [
    {
      "title": "Hurricane Marie threatens Labor Day weather",
      "slug": "hurricane-marie-threatens-labor-day-weather",
      "country": "US",
      "category": "weather",
      "articles": 57,
      "publishers": 24,
      "first_seen": "2026-09-05T19:24:36Z",
      "latest": "2026-09-06T19:00:04Z",
      "url": "https://freenewsapi.ai/trends/us/hurricane-marie-…",
      "headlines": [ … ]
    }
  ]
}

هر داستان با دو شمارش همراه است که معانی متفاوتی دارند. articles نشان‌دهنده بلندی صدا (تعداد) است و publishers نشان‌دهنده گستردگی (تعداد ناشران). داستانی با ۲۰۰ مقاله از ۴ نشریه، وسواس یک اتاق خبر است. داستانی با ۶۰ مقاله از ۴۰ نشریه، یک رویداد است. مرتب‌سازی پیش‌فرض بر اساس ناشران است و min_publishers / min_articles به شما امکان می‌دهند معیار خود را تعیین کنید.

داستان‌ها دسته‌بندی خود را از مجموعه‌ای ثابت دریافت می‌کنند: politics (سیاست)، business (کسب‌وکار)، markets (بازارها)، tech (فناوری)، sport (ورزش)، health (سلامت)، science (علوم)، culture (فرهنگ)، crime (جرم)، conflict (درگیری)، weather (آب‌وهوا)، society (جامعه).

پنجره زمانی انتخاب خواننده است، نه ربات

این یک تصمیم طراحی واقعاً ظریف است. هر مقاله با زمان انتشار خود ذخیره می‌شود و به داستان خود پیوسته است، بنابراین هر پنجره‌ای — پانزده دقیقه، یک ساعت، یک روز، یا یک تاریخ تقویمی خاص — صرفاً یک کوئری محدوده بر روی همان داده‌های ذخیره‌شده است. یک محاسبه، برای همه پنجره‌ها همزمان عمل می‌کند. window=15m، window=1h، window=24h، date=2026-09-01، یا یک جفت since/until صریح، همگی روی همان ایندکس بدون نیاز به محاسبه مجدد کار می‌کنند.

کلمات کلیدی: کلماتی که خبر بر آن‌ها بنا شده است

curl "https://freenewsapi.ai/v1/trends/keywords?country=US&size=8"

هر کلمه کلیدی با تعداد داستان‌های متمایزی که آن را حمل می‌کنند، تعداد مقالاتی که آن داستان‌ها دارند، و — مورد جالب‌تر — تعداد مطبوعات ملی که از آن استفاده می‌کنند بازگردانده می‌شود. آن عدد آخر، تفاوت بین یک رویداد جهانی و یک رویداد داخلی است. کلمه‌ای که در هفتاد کشور ظاهر می‌شود، یک داستان جهانی است؛ کلمه‌ای که بر مطبوعات یک کشور مسلط است، یک داستان داخلی است، هرچقدر هم که در آنجا بلند باشد.

کشورهای فعال

curl "https://freenewsapi.ai/v1/trends/countries"

تمام کشورهای تحت پوشش را با تعداد داستان‌های زنده و تعداد دقیقه‌هایی که از آخرین محاسبه مجدد آن‌ها می‌گذرد بازگردانده و ترکی، روسیه، ایران، یونان، هند، ایتالیا، اوکراین، رومانی، آرژانتین، آلمان و برزیل هم‌اکنون هر کدام هزاران داستان زنده دارند که در کمتر از ده دقیقه گذشته محاسبه مجدد شده‌اند. و /v1/trends/{cc}/{slug} هر داستان تکی را با فهرست کامل مقالات آن باز می‌کند.

بازارها در برابر پوشش خبری: قیمت در یک محور، توجه در محور دیگر

این غیرعادی‌ترین بخش سرویس است و وجود دارد زیرا مجموعه داده‌ها ساخت آن را تقریباً رایگان کرده است. یک سری قیمت را در کنار میزان نوشتن جهان درباره آن موضوع در همان ساعات، در یک خط زمانی قرار دهید.

curl "https://freenewsapi.ai/v1/markets"

چهارده ابزار در چهار کلاس دارایی تحت پوشش هستند:

curl "https://freenewsapi.ai/v1/markets/usd-try?window=30d"

همین یک فراخوان، نرخ لیر در برابر دلار و حجم پوشش خبری مطبوعات ترکیه را در همان بازه زمانی، هم‌تراز با ساعت‌ها در اختیار شما قرار می‌دهد. مطبوعات ترکیه بزرگ‌ترین بخش سوم این مجموعه داده هستند و دقیقاً به همین دلیل است که این جفت‌سازی، چیزی معنادار و نه نویز تولید می‌کند.

و یک بلوک کامل از احساسات بیت‌کوین

بیت‌کوین به یک خانوادهٔ هفت‌نقطه‌ای (endpoint) اختصاص یافته است، زیرا تنها ابزاری است که در مورد آن همواره دربارهٔ رابطهٔ میان لحن اخبار و حرکت قیمت بحث می‌شود و این رابطه به‌ندرت اندازه‌گیری می‌گردد:

برچسب‌های احساسی از یک مدل زبانی گرفته می‌شوند که هر پنج دقیقه بر روی مقالات تازه ارزهای دیجیتال اجرا می‌شود و با یک لیست سکه‌های کالیبره شده مقایسه می‌گردد. /v1/btc/correlation با پارامتر max_shift گزینه‌ای است که باید به آن مراجعه کنید اگر تا به حال خواسته‌اید ادعای «اخبار باعث حرکت بازار می‌شود» را به جای تکرار آن، آزمایش کنید.

همان جستجو، به‌عنوان یک فید

سه پایانه دیگر، پارامترهای جستجوی یکسان را دریافت کرده و نتایج را به‌جای JSON، به‌صورت فرمت‌های انتشار جمعی (Syndication) ارائه می‌دهند:

• GET /v1/rss — RSS 2.0
• GET /v1/atom — Atom 1.0
• GET /v1/feed.json — JSON Feed 1.1

https://freenewsapi.ai/v1/rss?q=semiconductor+export+controls&lang=en&date=7d&sort=date

این یعنی هر جستجوی ذخیره‌شده به یک فید تبدیل می‌شود که می‌توانید آن را در یک خواننده خبر، یک نود n8n، یک یکپارچه‌سازی Slack، یک تریگر Zapier یا یک تولیدکننده سایت استاتیک جایگذاری کنید — بدون نیاز به کدنویسی و بدون کلید. این یک ویژگی کوچک است که لایه یکپارچه‌سازی را به‌طور خاموش برای غیربرنامه‌نویسان حذف می‌کند.

MCP: بیست‌وهشت ابزار، دو لایه

سرور MCP در یک URL قرار دارد، از HTTP قابل اجرا (JSON-RPC 2.0 بر روی POST، نسخه پروتکل 2025-06-18) پشتیبانی می‌کند، قابلیت دسته‌بندی (Batching) دارد و — مانند همه چیزهای دیگر در اینجا — مرحله احراز هویت و شناسه نشست (Session ID) ندارد.

claude mcp add --transport http freenewsapi https://freenewsapi.ai/mcp

این سرور ۲۸ ابزار در دو لایه عمدی را ارائه می‌دهد.

لایه اول: شش میانبر که یک سوال کامل را در یک فراخوان پاسخ می‌دهند

لایه دوم: هر نقطه پایانی، از خود سرویس تولید شده است

زیر دست‌های میانبر، هر نقطه پایانی خام به عنوان ابزار مستقل با تمام پارامترهایی که API می‌پذیرد، در دسترس قرار می‌گیرد — news_get_search، news_get_stats، news_get_article، news_get_trends، news_get_trends_keywords، news_get_markets_slug، کل خانواده news_get_btc_*، رندرکننده‌های فید و news_get_health. این‌ها از سرویس زنده تولید می‌شوند، بنابراین نمی‌توانند از آنچه API واقعاً می‌پذیرد، منحرف شوند.

دو ابزار متا حلقه را می‌بندند: news_list_endpoints فهرست‌نامه‌ای از همه چیزهای موجود را برمی‌گرداند و news_get یک GET خام روی هر مسیر انجام می‌دهد — بنابراین عاملی که به نقطه پایانی برخورد می‌کند که لیست ابزارهایش آن را پوشش نمی‌دهد، همچنان می‌تواند به آن دسترسی پیدا کند.

curl "https://freenewsapi.ai/mcp?format=json"

یک GET، بدون دست دادن، و شما کل فهر‌نامه قابل خواندن توسط ماشین را دارید: سرور، انتقال، پروتکل، تعداد ابزارها، هر ابزار با توضیحاتش، و هر نقطه پایانی با فهرست پارامترهایش.

ساخته شده برای خواندن توسط ماشین‌ها

مستندات یک پس‌اندیشی که به API پیچانده شده نیست — بلکه یک خروجی درجه اول از آن است. سایت 665 صفحه استاتیک ارائه می‌دهد و چندین مورد از آن‌ها به طور خاص وجود دارند تا یک مدل مجبور نباشد HTML بخواند:

• /openapi.json نقشه کامل OpenAPI.
• /llms.txt یک فایل راهنمای کوتاه — معرفی سرویس، نقاط پایانی (endpoints)، نحوه پرس‌وجوی صحیح و خطاها.
• /llms-full.txt تمام مستندات در قالب یک فایل متنی ساده که بیش از صد کیلوبایت حجم دارد، تا یک عامل هوشمند (agent) بتواند کل راهنما را در یک بار دریافت، پردازش کند.
• /agents سیزده صفحه که مستقیماً برای سازندگان عامل‌های هوشمند (agent) طراحی شده‌اند: شامل تعریف‌های آماده توابع OpenAI، تعریف‌های استفاده از ابزار Anthropic، دستورات سیستم برای بازیابی اخبار، دستورالعمل‌های RAG، جداول هزینه توکن و دستورالعمل‌های ساخت عامل.
• /agents/models کدهای فراخوانی ابزار برای هر خانواده مدل — Qwen، DeepSeek، MiniMax، Kimi، GLM، Doubao، Hunyuan، ERNIE، Yi، Step، GPT، Claude، Gemini، Grok، Mistral، Llama، Command، Nova، Phi، Jamba، Sonar، OpenRouter، Ollama و vLLM.
• /data محتوای مجموعه داده، روش‌شناسی، طرح‌واره نمایه‌سازی (index schema) و صفحه‌ای با عنوان کیفیت داده که به مستندسازی خطاهای مجموعه داده می‌پردازد.
• /sources یک کاتالوگ قابل پیمایش شامل ۱۱٬۶۶۸ ناشر، که قابل فیلتر کردن بر اساس کشور، زبان و دامنه (domain zone) است.
• /compare صفحات مقایسه‌ای در کنار NewsAPI.org، GNews.io، NewsData.io، Mediastack، Currents، TheNewsAPI، NewsCatcher، WorldNewsAPI، Perigon، APITube و FreeNewsAPI.io.

به علاوه ۱۶۸ صفحه کشوری، ۱۲۱ صفحه زبانی و ۲۷۵ صفحه TLD — یک سطح قابل پیمایش برای هر بخش از مجموعه داده، که نشان می‌دهد در هر بخش واقعاً چه چیزی وجود دارد.

منبع مقالات

دو مسیر ورودی یک ایندکس را تغذیه می‌کنند و تفاوت بین آن‌ها اهمیت دارد.

مسیر آرشیو

هر ده دقیقه یک کار، آرشیو CC-NEWS Common Crawl را برای فایل‌های WARC جدید بررسی می‌کند و هر چیزی که قبلاً ندیده است را پردازش می‌کند، با استفاده از چهل کارگر موازی. استخراج‌کننده هر مقاله را از خزش خام با یک سلسله‌مراتب مستند برای هر فیلد بیرون می‌کشد — و سلسله‌مراتب‌ها بر روی داده‌های واقعی اندازه‌گیری شده‌اند، نه اینکه صرفاً فرض شوند:

این آمار کشور، صادقانه‌ترین بخش است و دلیل آن است که country_source در هر مقاله در دسترس قرار دارد: تقریباً یک‌پنجم از رکوردها هیچ سیگنال قابل اعتمادی درباره کشور ندارند و حدود یک‌سوم از مقادیری که وجود دارند، استنباطی هستند نه واقعیت. API مشخص می‌کند کدام‌یک کدام است، به جای اینکه وانمود کند.

مسیر زنده

یک ربات دوم، فیدهای ناشر RSS را هر پنج دقیقه بررسی می‌کند، در چرخشی همراه با درخواست‌های مشروط — فیدی که پاسخ 304 Not Modified می‌دهد هزینه‌ای ناچیز دارد، و بازه زمانی بررسی هر فید بر اساس میزان انتشار واقعی آن تنظیم شده است. رسانه‌ای که روزی پنج داستان منتشر می‌کند، هر پانزده دقیقه تحت فشار قرار نمی‌گیرد.

این سیستم همچنین تنها همان چیزی را دریافت می‌کند که ناشر در فید قرار داده است: عنوان، مقدمه و متن کامل زمانی که فید آن را حمل می‌کند. این سیستم برای دریافت اطلاعات بیشتر به سایت ناشر سر نمی‌زند. این یک مرز عمدی است و دلیل آن است که این سرویس می‌تواند تعهداتی را که در صفحه حقوقی خود برای ناشران ارائه می‌دهد، برآورده کند.

و ماشین‌آلات پیرامون آن‌ها

در اطراف دو مسیر دریافت، دوازده ربات دیگر بر اساس برنامه‌های زمانی فعالیت می‌کنند: کشف و همگام‌سازی منابع، حل کشور بر اساس دامنه، ساخت و بررسی روندها، پر کردن جای خالی کلمات کلیدی، احساسات ارزهای دیجیتال، دریافت‌های بازار، فهرست طبقه‌بندی، نگهداری (بازه نود روزه توسط یک کوئری شبانه روی published_at اعمال می‌شود، نه با سن ایندکس)، تأیید روزانه، بررسی مجدد مقالات خالی، و یک نگهبان سلامت که هر چیزی که متوقف شده است را مجدداً راه‌اندازی می‌کند. مجموعه داده‌ها روی یک خوشه Elasticsearch اختصاصی زندگی می‌کند.

چه چیزی در این مجموعه داده اشتباه است

این سرویس محدودیت‌های خود را منتشر می‌کند که سریع‌ترین راه برای قضاوت درباره اینکه آیا با مشکل شما سازگار است یا خیر، می‌باشد.

• کشور استنباطی است country_source را در هر مقاله بخوانید و strict_country=true را اضافه کنید زمانی که بر اساس کشور شمارش می‌کنید، نه زمانی که مرور می‌کنید.
• published_at توسط ناشر ارائه شده است تاریخ‌دهی معکوس رایج است. بر اساس crawled مرتب کنید زمانی که برای دریافت موارد جدید بررسی می‌کنید.
• total به 10,000 محدود شده است برای سرعت. total_is_lower_bound به شما می‌گوید زمانی که به سقف می‌رسید.
• بدون استخراج احساسات یا موجودیت‌ها خارج از بلاک بیت‌کوین، مقالات هیچ امتیاز احساسی و هیچ موجودیت نام‌گذاری شده‌ای ندارند. این موضوع در محدوده نیست.
• نود روز و بیشتر نه آرشیو عمیق‌تری وجود ندارد. اگر به سال ۲۰۱۹ نیاز دارید، این ابزار مناسب شما نیست.
• بدون SLA رایگان است. تحت نظارت و حفاظت نیز قرار دارد، اما هیچ تعهد کتبی‌ای وجود ندارد.
• متن متعلق به ناشران است هر پاسخ شامل URL اصلی است و از تماس‌گیرندگان انتظار می‌رود به آن ارجاع دهند.

استفاده صحیح: هزینه، صفحه‌بندی و خطاها

نظم در توکن‌ها

برای یک عامل هوشمند، اندازه پاسخ هزینه واقعی است. ساختار مستند آن:

بیست مقاله با full_text=true تقریباً ۴۰,۰۰۰ توکن است. الگوی توصیه‌شده همیشه یکسان است: شمارش، اسکن، و سپس دریافت بدنه برای موارد کمی که نیاز دارید.

پیمایش فراتر از سقف

offset در ۹,۹۰۰ متوقف می‌شود. برای پیمایش یک مجموعه بزرگ، با سقف رقابت نکنید — در عوض بر اساس زمان برش دهید. روز به روز، یا در یک کوئری شلوغ ساعت به ساعت، با استفاده از from/to و sort=date حلقه بزنید. مستندات یک صفحه اختصاصی درباره پیمایش یک روز کامل دارد.

خطاها

قرارداد صریح و ساده برای کدنویسی است: ۴xx به معنای اشتباه بودن درخواست است — آن را اصلاح کنید، نه اینکه دوباره تلاش کنید. ۵xx به معنای از کار افتادن سرویس است — عقب‌نشینی کنید. ۴۲۹ به معنای کندتر عمل کردن و تلاش مجدد است. پارامترهای کوئری ناشناس نادیده گرفته می‌شوند تا پس‌زمینه، بنابراین افزودن یک فیلد هرگز باعث خرابی برای فراخوان‌کننده موجود نمی‌شود.

خود را شناسایی کنید (اختیاری، و واقعاً اختیاری)

بدون کلید، هیچ راهی برای دسترسی به یک فراخوان‌کننده وجود ندارد. ادب پیشنهادی یک هدر است که نام عامل، چارچوبی که از طریق آن اجرا می‌شود و مدلی که آن را هدایت می‌کند را نام می‌برد:

X-Agent: agent_name=<agent>; software=<langchain|llamaindex|n8n|claude-desktop|cursor|openai-assistants|crewai|custom>; model=<model>; version=<v>; purpose=<rag|monitoring|research|digest>; contact=<url or mailto>
User-Agent: <agent>/<version> (+<contact url>)

همان مقادیر به عنوان پارامترهای کوئری ساده کار می‌کنند که معمولاً آسان‌تر است:

https://freenewsapi.ai/v1/search?q=climate&agent_name=newsbot&software=langchain&model=gpt-4o

کلیدهای ناشناس نادیده گرفته می‌شوند، بنابراین کلیدهای اضافی همیشه ایمن برای ارسال هستند. هیچ چیز اعتبارسنجی نمی‌شود، هیچ چیز برای حذف آن محدود نمی‌شود و تنها دستور قاطع است: هرگز داده‌های شخصی کاربر نهایی را در این فیلدها قرار ندهید.

در مقابل اخبار پولی APIها

صفحات مقایسه‌ای در سایت، یازده رقیب را به صورت جداگانه پوشش می‌دهند. تفاوت‌های ساختاری که از همه آن‌ها باقی می‌ماند:

آنچه سرویس‌های پولی هنوز به شما می‌دهند و این سرویس نمی‌دهد: امتیازهای احساسی و استخراج موجودیت به‌عنوان فیلدهای استاندارد، آرشیوهایی که به سال‌ها پیش برمی‌گردند، و قرارداد با SLA پشت آن. آن‌ها واقعی هستند و اگر به آن‌ها نیاز دارید باید آن‌ها را بخرید.

دستور پخت

پایش زنده کشور

curl "https://freenewsapi.ai/v1/search?country=UA&lang=uk&date=today&sort=crawled&size=50"

آیا این داستان جهانی است یا داخلی؟

curl "https://freenewsapi.ai/v1/trends/keywords?size=30"
# read `countries` on each keyword: 1 country = domestic, 70 = world event

مدل را به‌طور ارزان در پوشش امروز زمین‌گیر کنید

# 1. count first
curl "https://freenewsapi.ai/v1/stats?q=semiconductor+export+controls&date=7d"
# 2. scan metadata
curl "https://freenewsapi.ai/v1/search?q=semiconductor+export+controls&date=7d&lang=en&size=20&sort=relevance"
# 3. fetch bodies for the three you picked
curl "https://freenewsapi.ai/v1/article?url=<exact-url>&full_text=true"

آیا پوشش قیمت را هدایت می‌کند؟

curl "https://freenewsapi.ai/v1/btc/correlation?interval=hour&max_shift=12"

یک جستجوی ذخیره‌شده را به یک فید تبدیل کنید

https://freenewsapi.ai/v1/rss?q=central+bank+rate&lang=en&date=24h&sort=date&size=50

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

curl "https://freenewsapi.ai/v1/stats?country=BR&date=30d&top=50"
# the `hosts` block is a ranked publisher list for that slice

خلاصه

Free News API یک جستجوی متن کامل بر روی بیش از ۲۱.۵ میلیون مقاله خبری از بیش از ۲۵,۰۰۰ ناشر در ۱۰۰ کشور و حدود ۱۰۰ زبان است که در یک پنجره زمانی ۹۰ روزه متحرک، به‌طور پیوسته به‌روز می‌شود و بدون نیاز به کلید، ثبت‌نام و محدودیت حجم (فراتر از محدودیت نرخ بر اساس IP) ارائه می‌شود. علاوه بر جستجو، خوشه‌بندی زنده داستان‌ها بر اساس کشور در ۱۱۵ کشور، تحلیل کلیدواژه‌ها که رویدادهای جهانی را از داخلی تفکیک می‌کند، پلات چهارده ابزار بازار در برابر حجم پوشش خبری، بلاک احساسات بیت‌کوین با هفت نقطه پایانی، سیندیکیشن RSS/Atom/JSON برای هر کوئری و سرور MCP با ۲۸ ابزار که از خود سرویس تولید می‌شود، قرار دارد.

نرخ خطاهای خود را مستند می‌کند، نحوه استخراج هر مقدار کشور را آشکار می‌سازد و صفحه‌ای درباره اینکه داده‌ها چه چیزهایی را اشتباه ارائه می‌دهند، منتشر می‌کند. برای عاملی که نیاز دارد بداند جهان چه می‌گوید — به ترکی، به یونانی، به هندی، در همین لحظه — این ترکیب به هر قیمتی یافتن آن دشوار است و این سرویس رایگان است.

جستجو بر اساس AND (و) برای تمام عبارات است. از ۲ تا ۵ کلیدواژه استفاده کنید، نه یک سوال به زبان طبیعی.

Free News API، درباره نحوه کوئری دادن صحیح

از اینجا شروع کنید: freenewsapi.ai · MCP در freenewsapi.ai/mcp · کل راهنما به صورت یک فایل در /llms-full.txt.