Schnellstart

Schlüssel holen, Zeile kopieren, ausführen, JSON lesen.

0. Schlüssel erhalten

Erstellen Sie ein kostenloses Konto, öffnen Sie API-Schlüssel und erstellen Sie einen. Bewahren Sie ihn dann in einer Umgebungsvariable auf:

export FNA_KEY=fna_live_...

1. Suchen

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"
    }
  ]
}

Drei Felder in dieser Antwort sind sofort bemerkenswert. total gibt an, wie viele Artikel übereingestimmt haben, nicht wie viele zurückgegeben wurden – dieser Wert ist aus Leistungsgründen auf 10,000 begrenzt, und total_is_lower_bound teilt Ihnen mit, wann diese Grenze erreicht wurde. country_source zeigt, wie das Land bestimmt wurde, was wichtig ist, da etwa ein Drittel der Länderangaben in jedem Nachrichtendatensatz auf Schätzungen und nicht auf Fakten basiert. Und crawled_at ist der ehrliche Zeitstempel: Verlage können published_at zurückdatieren, aber die Crawl-Zeit wird vom System zugewiesen.

2. Eingrenzen

Filter kombinieren sich mit UND über Parameter hinweg und mit ODER innerhalb eines Parameters. country=DE,AT&lang=de liest sich also als „Deutschsprachige Artikel aus Deutschland oder Österreich“. Dies fragt nach heutigen ukrainischsprachigen Artikeln aus der Ukraine, sortiert nach Neuesten:

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

3. Den vollständigen Text erhalten

Suchergebnisse enthalten standardmäßig keinen Artikeltext, um die Antwortgröße gering zu halten. Fordern Sie den Text explizit an, sobald Sie die gewünschten Artikel ausgewählt haben:

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

4. Zählen statt auflisten

Oft ist die nützliche Frage nicht „Was sind die Artikel“, sondern „Gibt es hier überhaupt etwas, und wo ist es?“. Das Zählen von Antworten kostet einen Bruchteil der Kosten – etwa 200 Tokens im Vergleich zu mehreren Tausend für eine Ergebnisseite – was es zum richtigen ersten Aufruf für einen Agenten macht, der entscheidet, ob eine Suche lohnenswert ist:

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

Die Antwort enthält Zählungen nach Land, Sprache, Domain-Endung, Verlag und Tag, berechnet über die gesamte Treffermenge und nicht nur über die aktuelle Seite.

In 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"])

In 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));

Weiter