الصفحة الرئيسية › توثيق 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));

بداية سريعة

0. الحصول على مفتاح المصادقة

1. البحث

2. تضييق نطاق البحث

3. الحصول على نص المقال الكامل

4. الاعتماد على العد بدلاً من سرد القائمة

في بايثون

في جافا سكريبت

التالي

كل معلمة

ربط وكيل

تصفح يوم كامل