Avvio rapido

Ottieni una chiave, copia la riga, eseguila, leggi il JSON.

0. Ottieni una chiave

Crea un account gratuito, apri API keys e creane una. Poi tienila in una variabile d'ambiente:

export FNA_KEY=fna_live_...

1. Cerca

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

Tre campi della risposta meritano un'attenzione immediata. total indica il numero di articoli corrispondenti, non quelli restituiti: è limitato a 10,000 per garantire velocità, e total_is_lower_bound ti avvisa quando si raggiunge questo limite. country_source specifica come è stato determinato il paese, aspetto rilevante perché circa un terzo dei valori di paese nei dataset di notizie sono stime piuttosto che dati certi. E crawled_at è il timestamp onesto: gli editori possono retrodatare published_at, ma l'orario di crawling è assegnato dalla pipeline.

2. Affina la ricerca

I filtri combinano AND tra i parametri e OR all'interno di uno stesso parametro. Quindi country=DE,AT&lang=de si legge come "articoli in lingua tedesca provenienti dalla Germania o dall'Austria". Questa richiesta cerca gli articoli in lingua ucraina di oggi dall'Ucraina, ordinati dal più recente al più vecchio:

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

3. Ottieni il testo completo

I risultati della ricerca omettono il corpo dell'articolo per mantenere le risposte leggere. Richiedilo esplicitamente solo quando hai selezionato gli articoli che ti interessano davvero:

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

4. Conta invece di elencare

Spesso la domanda utile non è "quali sono gli articoli" ma "c'è qualcosa qui, e dove si trova". Contare le risposte costa una frazione del prezzo — circa 200 token contro diversi migliaia per una pagina di risultati — rendendola la chiamata iniziale ideale per un agente che deve decidere se vale la pena eseguire una ricerca:

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

La risposta fornisce i conteggi per paese, lingua, zona del dominio, editore e giorno, calcolati sull'intero insieme di risultati corrispondenti e non solo sulla pagina corrente.

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

Avanti