From 1 November 2026 the API needs a free key. Calls without one work until then. Get a key · what changes
FA
EnglishУкраїнськаEspañolPortuguêsDeutschFrançaisItalianoPolskiNederlandsSvenskaDanskNorskSuomiČeštinaRomânăMagyarΕλληνικάTürkçeالعربيةעבריתفارسیहिन्दीবাংলাIndonesiaMelayuTiếng Việtไทย日本語한국어中文
وروددریافت کلید API
خانه › مستندات API › شروع سریع

شروع سریع

کلید بگیرید، خط را کپی کنید، اجرا کنید، JSON را بخوانید.

0. کلید دریافت کنید

یک حساب رایگان ایجاد کنید، کلیدهای API را باز کنید و یکی بسازید. سپس آن را در یک متغیر محیطی نگه دارید:

bash
export FNA_KEY=fna_live_...

1. جستجو

bash
curl -H "Authorization: Bearer $FNA_KEY" "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 تعداد مقالات مطابقت‌یافته است، نه تعداد مقالات بازگردانده‌شده — این مقدار برای سرعت به 10,000 محدود شده است و total_is_lower_bound به شما اطلاع می‌دهد که به این محدودیت رسیده‌اید. country_source نشان می‌دهد که کشور چگونه تعیین شده است که مهم است، زیرا تقریباً یک‌سوم مقادیر کشور در هر مجموعه خبری، استنباطی هستند تا واقعیت. و crawled_at یک زمان‌بندی صادقانه است: ناشران می‌توانند published_at را تاریخ‌گذاری معکوس کنند، اما زمان خزیدن توسط پایپ‌لاین تعیین می‌شود.

2. محدودتر کنید

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

bash
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?country=UA&lang=uk&date=today&sort=date&size=10"

3. متن کامل را دریافت کنید

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

bash
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/search?q=inflation&full_text=true&size=5"

متن کامل هر مقاله تقریباً 2,000 تا 4,000 کاراکتر است. بیست مقاله با full_text=true حدود 40,000 توکن برای یک مدل زبانی مصرف می‌کند. ابتدا انتخاب کنید، سپس بدنه مقالات را دریافت کنید. به هزینه‌های توکن مراجعه کنید.

4. به جای لیست کردن، شمارش کنید

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

bash
curl -H "Authorization: Bearer $FNA_KEY" "https://freenewsapi.ai/v1/stats?q=earthquake&date=7d"

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

در پایتون

python
import os, requests
HEADERS = {"Authorization": "Bearer " + os.environ["FNA_KEY"]}

r = requests.get("https://freenewsapi.ai/v1/search", headers=HEADERS, params={
    "q": "semiconductor export controls",
    "date": "7d",
    "lang": "en",
    "size": 20,
    "sort": "relevance",
})
for a in r.json()["results"]:
    print(a["published_at"], a["host"], a["title"])

در جاوااسکریپت

javascript
const url = new URL("https://freenewsapi.ai/v1/search");
url.search = new URLSearchParams({ q: "central bank", date: "24h", size: "20" });

const { results } = await (await fetch(url, { headers: { Authorization: `Bearer ${FNA_KEY}` } })).json();
results.forEach(a => console.log(a.published_at, a.host, a.title));

بعدی